<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="icon" href="images/favicon.ico" />
    <link rel="canonical" href="http://bookshelfjs.org" />
    <title>Bookshelf.js | API Reference</title>
    <!--
    ._.                                                      ._.
    | |    ______             _        _          _  __      | |
    | |    | ___ \           | |      | |        | |/ _|     | |
    | |    | |_/ / ___   ___ | | _____| |__   ___| | |_      | |
    | |    | ___ \/ _ \ / _ \| |/ / __| '_ \ / _ \ |  _|     | |
    | |    | |_/ / (_) | (_) |   <\__ \ | | |  __/ | |       | |
    | |____\____/_\___/_\___/|_|\_\___/_|_|_|\___|_|_|_______| |
    |                                                          |
    \________\  /__________________________________\  /________/
              \/                                    \/
    -->
    <script src="scripts/prettify/prettify.js"></script>
    <script src="scripts/prettify/lang-css.js"></script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->

    <!-- Import fonts from Open Font Library -->
    <link rel="stylesheet" media="screen" href="https://fontlibrary.org/face/carlito" rel="stylesheet" type="text/css"/>
    <link rel="stylesheet" media="screen" href="https://fontlibrary.org/face/average-mono" rel="stylesheet" type="text/css"/>
    <link rel="stylesheet" media="screen" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" type="text/css"/>

    <link type="text/css" rel="stylesheet" href="styles/main.css">
  </head>
  <body class="minami">
    <nav class="main-navbar">
      <a href="index.html"><img class="nav-logo" src="images/bookshelf-icon-inverted.svg" />Bookshelf.js
</a>
      <label for="show-menu" class="show-menu">
        <i class="fa fa-bars fa-lg" aria-hidden="true"></i>
      </label>
      <input type="checkbox" id="show-menu" role="button" checked>
      <ul id="menu">
        
          <li>
            <a href="tutorials.html"><i class="fa fa-file-text" aria-hidden="true"></i>Guides
</a>
          </li>
        
        
          <li>
            <a href="api.html" class="active"><i class="fa fa-book" aria-hidden="true"></i>API Reference
</a>
          </li>
        
        <li>
          <a href="https://github.com/bookshelf/bookshelf"><span class="fa fa-github"></span></a>
        </li>
      </ul>
    </nav>

    <div class="page-content">
      
        <nav class="sidebar">
          
            <ul><li><h3><a href="api.html#section-Bookshelf">Bookshelf</a></h3><h4><a href="api.html#Bookshelf-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Bookshelf">Bookshelf</a></li></ul><h4><a href="api.html#Bookshelf-subsection-members">Members</a></h4><ul class="members"><li><a href="api.html#Bookshelf-instance-knex">knex</a></li></ul><h4><a href="api.html#Bookshelf-subsection-methods">Methods</a></h4><ul class="methods"><li><a href="api.html#Bookshelf-instance-model">model</a></li><li><a href="api.html#Bookshelf-instance-plugin">plugin</a></li><li><a href="api.html#Bookshelf-instance-resolve">resolve</a></li><li><a href="api.html#Bookshelf-instance-transaction">transaction</a></li></ul></li><li><h3><a href="api.html#section-Model">Model</a></h3><h4><a href="api.html#Model-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Model">Model</a></li><li><a href="api.html#Model-instance-initialize">initialize</a></li></ul><h4><a href="api.html#Model-subsection-static">Static</a></h4><ul class="static"><li><a href="api.html#Model-static-collection">collection</a></li><li><a href="api.html#Model-static-count">count</a></li><li><a href="api.html#Model-static-extend">extend</a></li><li><a href="api.html#Model-static-fetchAll">fetchAll</a></li><li><a href="api.html#Model-static-forge">forge</a></li></ul><h4><a href="api.html#Model-subsection-members">Members</a></h4><ul class="members"><li><a href="api.html#Model-instance-defaults">defaults</a></li><li><a href="api.html#Model-instance-hasTimestamps">hasTimestamps</a></li><li><a href="api.html#Model-instance-hidden">hidden</a></li><li><a href="api.html#Model-instance-id">id</a></li><li><a href="api.html#Model-instance-idAttribute">idAttribute</a></li><li><a href="api.html#Model-instance-requireFetch">requireFetch</a></li><li><a href="api.html#Model-instance-tableName">tableName</a></li><li><a href="api.html#Model-instance-visible">visible</a></li></ul><h4><a href="api.html#Model-subsection-methods">Methods</a></h4><ul class="methods"><li><a href="api.html#Model-instance-belongsTo">belongsTo</a></li><li><a href="api.html#Model-instance-belongsToMany">belongsToMany</a></li><li><a href="api.html#Model-instance-clear">clear</a></li><li><a href="api.html#Model-instance-clone">clone</a></li><li><a href="api.html#Model-instance-count">count</a></li><li><a href="api.html#Model-instance-destroy">destroy</a></li><li><a href="api.html#Model-instance-escape">escape</a></li><li><a href="api.html#Model-instance-fetch">fetch</a></li><li><a href="api.html#Model-instance-fetchAll">fetchAll</a></li><li><a href="api.html#Model-instance-fetchPage">fetchPage</a></li><li><a href="api.html#Model-instance-format">format</a></li><li><a href="api.html#Model-instance-get">get</a></li><li><a href="api.html#Model-instance-has">has</a></li><li><a href="api.html#Model-instance-hasChanged">hasChanged</a></li><li><a href="api.html#Model-instance-hasMany">hasMany</a></li><li><a href="api.html#Model-instance-hasOne">hasOne</a></li><li><a href="api.html#Model-instance-isNew">isNew</a></li><li><a href="api.html#Model-instance-load">load</a></li><li><a href="api.html#Model-instance-morphMany">morphMany</a></li><li><a href="api.html#Model-instance-morphOne">morphOne</a></li><li><a href="api.html#Model-instance-morphTo">morphTo</a></li><li><a href="api.html#Model-instance-off">off</a></li><li><a href="api.html#Model-instance-on">on</a></li><li><a href="api.html#Model-instance-once">once</a></li><li><a href="api.html#Model-instance-orderBy">orderBy</a></li><li><a href="api.html#Model-instance-parse">parse</a></li><li><a href="api.html#Model-instance-previous">previous</a></li><li><a href="api.html#Model-instance-previousAttributes">previousAttributes</a></li><li><a href="api.html#Model-instance-query">query</a></li><li><a href="api.html#Model-instance-refresh">refresh</a></li><li><a href="api.html#Model-instance-related">related</a></li><li><a href="api.html#Model-instance-resetQuery">resetQuery</a></li><li><a href="api.html#Model-instance-save">save</a></li><li><a href="api.html#Model-instance-serialize">serialize</a></li><li><a href="api.html#Model-instance-set">set</a></li><li><a href="api.html#Model-instance-through">through</a></li><li><a href="api.html#Model-instance-timestamp">timestamp</a></li><li><a href="api.html#Model-instance-toJSON">toJSON</a></li><li><a href="api.html#Model-instance-trigger">trigger</a></li><li><a href="api.html#Model-instance-triggerThen">triggerThen</a></li><li><a href="api.html#Model-instance-unset">unset</a></li><li><a href="api.html#Model-instance-where">where</a></li></ul><h4><a href="api.html#Model-subsection-lodash-methods">Lodash Methods</a></h4><ul class="lodash-methods"><li><a href="api.html#Model-instance-omit">omit</a></li><li><a href="api.html#Model-instance-pick">pick</a></li></ul><h4><a href="api.html#Model-subsection-events">Events</a></h4><ul class="events"><li><a href="api.html#Model-event-counting">counting</a></li><li><a href="api.html#Model-event-created">created</a></li><li><a href="api.html#Model-event-creating">creating</a></li><li><a href="api.html#Model-event-destroyed">destroyed</a></li><li><a href="api.html#Model-event-destroying">destroying</a></li><li><a href="api.html#Model-event-fetched">fetched</a></li><li><a href="api.html#Model-event-fetching">fetching</a></li><li><a href="api.html#Model-event-saved">saved</a></li><li><a href="api.html#Model-event-saving">saving</a></li><li><a href="api.html#Model-event-updated">updated</a></li><li><a href="api.html#Model-event-updating">updating</a></li><li><a href="api.html#Model-instance-fetched:collection">fetched:collection</a></li><li><a href="api.html#Model-instance-fetching:collection">fetching:collection</a></li></ul></li><li><h3><a href="api.html#section-Model-static-NoRowsDeletedError">NoRowsDeletedError</a></h3><h4><a href="api.html#Model-static-NoRowsDeletedError-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Model-static-NoRowsDeletedError">NoRowsDeletedError</a></li></ul></li><li><h3><a href="api.html#section-Model-static-NoRowsUpdatedError">NoRowsUpdatedError</a></h3><h4><a href="api.html#Model-static-NoRowsUpdatedError-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Model-static-NoRowsUpdatedError">NoRowsUpdatedError</a></li></ul></li><li><h3><a href="api.html#section-Model-static-NotFoundError">NotFoundError</a></h3><h4><a href="api.html#Model-static-NotFoundError-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Model-static-NotFoundError">NotFoundError</a></li></ul></li><li><h3><a href="api.html#section-Collection">Collection</a></h3><h4><a href="api.html#Collection-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Collection">Collection</a></li><li><a href="api.html#Collection-instance-initialize">initialize</a></li></ul><h4><a href="api.html#Collection-subsection-static">Static</a></h4><ul class="static"><li><a href="api.html#Collection-static-extend">extend</a></li><li><a href="api.html#Collection-static-forge">forge</a></li></ul><h4><a href="api.html#Collection-subsection-members">Members</a></h4><ul class="members"><li><a href="api.html#Collection-instance-count">count</a></li><li><a href="api.html#Collection-instance-create">create</a></li><li><a href="api.html#Collection-instance-fetch">fetch</a></li><li><a href="api.html#Collection-instance-fetchOne">fetchOne</a></li><li><a href="api.html#Collection-instance-length">length</a></li><li><a href="api.html#Collection-instance-load">load</a></li></ul><h4><a href="api.html#Collection-subsection-methods">Methods</a></h4><ul class="methods"><li><a href="api.html#Collection-instance-add">add</a></li><li><a href="api.html#Collection-instance-at">at</a></li><li><a href="api.html#Collection-instance-attach">attach</a></li><li><a href="api.html#Collection-instance-clone">clone</a></li><li><a href="api.html#Collection-instance-detach">detach</a></li><li><a href="api.html#Collection-instance-first">first</a></li><li><a href="api.html#Collection-instance-get">get</a></li><li><a href="api.html#Collection-instance-invokeThen">invokeThen</a></li><li><a href="api.html#Collection-instance-last">last</a></li><li><a href="api.html#Collection-instance-off">off</a></li><li><a href="api.html#Collection-instance-on">on</a></li><li><a href="api.html#Collection-instance-once">once</a></li><li><a href="api.html#Collection-instance-orderBy">orderBy</a></li><li><a href="api.html#Collection-instance-parse">parse</a></li><li><a href="api.html#Collection-instance-pluck">pluck</a></li><li><a href="api.html#Collection-instance-pop">pop</a></li><li><a href="api.html#Collection-instance-push">push</a></li><li><a href="api.html#Collection-instance-query">query</a></li><li><a href="api.html#Collection-instance-reduceThen">reduceThen</a></li><li><a href="api.html#Collection-instance-remove">remove</a></li><li><a href="api.html#Collection-instance-reset">reset</a></li><li><a href="api.html#Collection-instance-serialize">serialize</a></li><li><a href="api.html#Collection-instance-set">set</a></li><li><a href="api.html#Collection-instance-shift">shift</a></li><li><a href="api.html#Collection-instance-slice">slice</a></li><li><a href="api.html#Collection-instance-through">through</a></li><li><a href="api.html#Collection-instance-toJSON">toJSON</a></li><li><a href="api.html#Collection-instance-trigger">trigger</a></li><li><a href="api.html#Collection-instance-triggerThen">triggerThen</a></li><li><a href="api.html#Collection-instance-unshift">unshift</a></li><li><a href="api.html#Collection-instance-updatePivot">updatePivot</a></li><li><a href="api.html#Collection-instance-where">where</a></li><li><a href="api.html#Collection-instance-withPivot">withPivot</a></li></ul><h4><a href="api.html#Collection-subsection-lodash-methods">Lodash Methods</a></h4><ul class="lodash-methods"><li><a href="api.html#Collection-instance-countBy">countBy</a></li><li><a href="api.html#Collection-instance-every">every</a></li><li><a href="api.html#Collection-instance-filter">filter</a></li><li><a href="api.html#Collection-instance-find">find</a></li><li><a href="api.html#Collection-instance-forEach">forEach</a></li><li><a href="api.html#Collection-instance-groupBy">groupBy</a></li><li><a href="api.html#Collection-instance-includes">includes</a></li><li><a href="api.html#Collection-instance-invokeMap">invokeMap</a></li><li><a href="api.html#Collection-instance-isEmpty">isEmpty</a></li><li><a href="api.html#Collection-instance-map">map</a></li><li><a href="api.html#Collection-instance-reduce">reduce</a></li><li><a href="api.html#Collection-instance-reduceRight">reduceRight</a></li><li><a href="api.html#Collection-instance-reject">reject</a></li><li><a href="api.html#Collection-instance-some">some</a></li><li><a href="api.html#Collection-instance-sortBy">sortBy</a></li><li><a href="api.html#Collection-instance-toArray">toArray</a></li></ul><h4><a href="api.html#Collection-subsection-events">Events</a></h4><ul class="events"><li><a href="api.html#Collection-event-fetched">fetched</a></li></ul></li><li><h3><a href="api.html#section-Collection-static-EmptyError">EmptyError</a></h3><h4><a href="api.html#Collection-static-EmptyError-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Collection-static-EmptyError">EmptyError</a></li></ul></li><li><h3><a href="api.html#section-Events">Events</a></h3><h4><a href="api.html#Events-subsection-construction">Construction</a></h4><ul class="construction"><li><a href="api.html#Events">Events</a></li></ul><h4><a href="api.html#Events-subsection-methods">Methods</a></h4><ul class="methods"><li><a href="api.html#Events-instance-off">off</a></li><li><a href="api.html#Events-instance-on">on</a></li><li><a href="api.html#Events-instance-once">once</a></li><li><a href="api.html#Events-instance-trigger">trigger</a></li><li><a href="api.html#Events-instance-triggerThen">triggerThen</a></li></ul></li></ul>
          
        </nav>
      

      <div class="main-container api">
        <div class="main-column">
          

          




<header>
    <h1>API Reference</h1>
</header>


<article>
    
        <h2 id="section-Bookshelf">Bookshelf</h2>
        
            <div class="class-description"><p>The Bookshelf library is initialized by passing an initialized Knex client
instance. The knex documentation provides a number of examples for different
databases.</p></div>
        
    

    <div class="container-overview">
    
        <h3
          id="Bookshelf-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method no-description">
    

        <h4 id="Bookshelf" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="parameters"><span class="name"><a href="api.html#Bookshelf">Bookshelf</a></span><span class="parenthesis">(</span><span class="item-name">knex</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_bookshelf.js.html#line31" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">knex</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Knex</code
>
</span></code>
      

      <div class="description">
        <p>Knex instance.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
</div>

        

    
    </div>

    

    

     

    

    

    
        <h3
          id="Bookshelf-subsection-members"
          class="subsection-title"
        >Members</h3>
        
            
<div class="method has-description">
    

        <h4 id="Bookshelf-instance-knex" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >bookshelf</span
                >.</span><span class="name"><a href="api.html#Bookshelf-instance-knex">knex</a></span><span class="type-signature"> :Knex</span>
          <a href="lib_bookshelf.js.html#line522" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>A reference to the <a href="http://knexjs.org">Knex.js</a> instance being used by Bookshelf.</p>
    </div>
  
</div>

        
    

    
        <h3
          id="Bookshelf-subsection-methods"
          class="subsection-title"
        >Methods</h3>
        <div class="methods">
          
              
<div class="method has-description">
    

        <h4 id="Bookshelf-instance-model" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >bookshelf</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Bookshelf-instance-model">model</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">Model</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">staticProperties</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_bookshelf.js.html#line118" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Defining and registering a model
module.exports = bookshelf.model('Customer', {
  tableName: 'customers',
  orders() {
    return this.hasMany('Order')
  }
})

// Retrieving a previously registered model
const Customer = bookshelf.model('Customer')

// Registering already defined models
// file: customer.js
const Customer = bookshelf.Model.extend({
  tableName: 'customers',
  orders() {
    return this.hasMany('Order')
  }
})
module.exports = bookshelf.model('Customer', Customer)

// file: order.js
const Order = bookshelf.Model.extend({
  tableName: 'orders',
  customer() {
    return this.belongsTo('Customer')
  }
})
module.exports = bookshelf.model('Order', Order)</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name to save the model as, or the name of the model to retrieve if no further arguments are passed to this
method.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">Model</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>The model to register. If a plain object is passed it will be converted to a <a href="api.html#Model"><code>Model</code></a>. See example above.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">staticProperties</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>If a plain object is passed as second argument, this can be used to specify additional static properties and
methods for the new model that is created.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The registered model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Registers a model. Omit the second argument <code>Model</code> to return a previously registered model that matches the
provided name.</p>
<p>Note that when registering a model with this method it will also be available to all relation methods, allowing
you to use a string name in that case. See the calls to <code>hasMany()</code> in the examples above.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Bookshelf-instance-plugin" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >bookshelf</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Bookshelf-instance-plugin">plugin</a></span><span class="parenthesis">(</span><span class="item-name">plugin</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Bookshelf">Bookshelf</a></span>
          <a href="lib_bookshelf.js.html#line414" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">plugin</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >array</code
><code class="type-or">|</code><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>The plugin or plugins to load. If you provide a string it can
represent an npm package or a file somewhere on your project. You can
also pass a function as argument to add it as a plugin. Finally, it's
also possible to pass an array of strings or functions to add them all
at once.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>This can be anything you want and it will be passed directly to the
plugin as the second argument when loading it.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Bookshelf">Bookshelf</a></code
>




<span class="param-desc">
  <p>The bookshelf instance for chaining.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This method provides a nice, tested, standardized way of adding plugins
to a <code>Bookshelf</code> instance, injecting the current instance into the
plugin, which should be a <code>module.exports</code>.</p>
<p>You can add a plugin by specifying a string with the name of the plugin
to load. In this case it will try to find a module. It will pass the
string to <code>require()</code>, so you can either require a third-party dependency
by name or one of your own modules by relative path:</p>
<pre><code>bookshelf.plugin('./bookshelf-plugins/my-favourite-plugin');
bookshelf.plugin('plugin-from-npm');
</code></pre>
<p>There are a few official plugins published in <code>npm</code>, along with many
independently developed ones. See
<a href="index.html#official-plugins">the list of available plugins</a>.</p>
<p>You can also provide an array of strings or functions, which is the same
as calling <code>bookshelf.plugin()</code> multiple times. In this case the same
options object will be reused:</p>
<pre><code>bookshelf.plugin(['cool-plugin', './my-plugins/even-cooler-plugin']);
</code></pre>
<p>Example plugin:</p>
<pre><code>// Converts all string values to lower case when setting attributes on a model
module.exports = function(bookshelf) {
  bookshelf.Model = bookshelf.Model.extend({
    set(key, value, options) {
      if (!key) return this
      if (typeof value === 'string') value = value.toLowerCase()
      return bookshelf.Model.prototype.set.call(this, key, value, options)
    }
  })
}</code></pre>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Bookshelf-instance-resolve" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >bookshelf</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Bookshelf-instance-resolve">resolve</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  *</span>
          <a href="lib_bookshelf.js.html#line148" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Customer = bookshelf.model('Customer', {
  tableName: 'customers'
})

bookshelf.resolve = (name) => {
  if (name === 'SpecialCustomer') return Customer;
}</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The model name to resolve.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >*</code
>




<span class="param-desc">
  <p>The return value will depend on what your re-implementation of this function does.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Override this in your bookshelf instance to define a custom function that will resolve the location of a model or
collection when using the <a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a> method or when passing a string with a model name in any of the
collection methods (e.g. <a href="api.html#Model-instance-hasOne"><code>Model#hasOne</code></a>, <a href="api.html#Model-instance-hasMany"><code>Model#hasMany</code></a>, etc.).</p>
<p>This will only be used if the specified name cannot be found in the registry. Note that this function
can return anything you'd like, so it's not restricted in functionality.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Bookshelf-instance-transaction" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >bookshelf</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Bookshelf-instance-transaction">transaction</a></span><span class="parenthesis">(</span><span class="item-name">transactionCallback</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise</span>
          <a href="lib_bookshelf.js.html#line346" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var Promise = require('bluebird')

Bookshelf.transaction((t) => {
  return new Library({name: 'Old Books'})
    .save(null, {transacting: t})
    .tap(function(model) {
      return Promise.map([
        {title: 'Canterbury Tales'},
        {title: 'Moby Dick'},
        {title: 'Hamlet'}
      ], (info) => {
        return new Book(info).save({'shelf_id': model.id}, {transacting: t})
      })
    })
}).then((library) => {
  console.log(library.related('books').pluck('title'))
}).catch((err) => {
  console.error(err)
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">transactionCallback</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Bookshelf~transactionCallback">Bookshelf~transactionCallback</a></code
>
</span></code>
      

      <div class="description">
        <p>Callback containing transaction logic. The callback should return a Promise.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>A promise resolving to the value returned from
<a href="api.html#Bookshelf~transactionCallback"><code>transactionCallback</code></a>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>An alias to <code><code>Knex#transaction</code></code>. The <code>transaction</code>
object must be passed along in the options of any relevant Bookshelf calls, to ensure all
queries are on the same connection. The entire transaction block is wrapped around a Promise
that will commit the transaction if it resolves successfully, or roll it back if the Promise
is rejected.</p>
<p>Note that there is no need to explicitly call <code>transaction.commit()</code> or
<code>transaction.rollback()</code> since the entire transaction will be committed if there are no
errors inside the transaction block.</p>
<p>When fetching inside a transaction it's possible to specify a row-level lock by passing the
wanted lock type in the <code>lock</code> option to <a href="api.html#Model-instance-fetch"><code>fetch</code></a>. Available options are
<code>lock: 'forUpdate'</code> and <code>lock: 'forShare'</code>.</p>
    </div>
  
</div>

          
        </div>
    

    

    
        <h3 class="subsection-title">Type Definitions</h3>

        
                
<div class="method has-description">
    

        <h4 id="Bookshelf~transactionCallback" class="item-header">
          <span class="type-signature"></span>
          
          <span class="parameters"><span class="name"><a href="api.html#Bookshelf~transactionCallback">transactionCallback</a></span><span class="parenthesis">(</span><span class="item-name">transaction</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise</span>
          <a href="lib_bookshelf.js.html#line393" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">transaction</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="http://knexjs.org/#Transactions">Knex#transaction</a></li>
        
            <li><a href="api.html#Bookshelf-instance-transaction">Bookshelf#transaction</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>The Promise will resolve to the return value of the callback, or be rejected with an error
thrown inside it. If it resolves, the entire transaction is committed, otherwise it is
rolled back.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This is a transaction block to be provided to <a href="api.html#Bookshelf-instance-transaction"><code>Bookshelf#transaction</code></a>. All of the
database operations inside it can be part of the same transaction by passing the
<code>transacting: transaction</code> option to <a href="api.html#Model-instance-fetch"><code>fetch</code></a>, <a href="api.html#Model-instance-save"><code>save</code></a> or
<a href="api.html#Model-instance-destroy"><code>destroy</code></a>.</p>
<p>Note that unless you explicitly pass the <code>transaction</code> object along to any relevant model
operations, those operations will not be part of the transaction, even though they may be
inside the transaction callback.</p>
    </div>
  
</div>

            
    

    
</article>











<article>
    
        <h2 id="section-Model">Model</h2>
        
            <div class="class-description"><p>Models are simple objects representing individual database rows, specifying
the tableName and any relations to other models. They can be extended with
any domain-specific methods, which can handle components such as validations,
computed properties, and access control.</p></div>
        
    

    <div class="container-overview">
    
        <h3
          id="Model-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Model" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="parameters"><span class="name"><a href="api.html#Model">Model</a></span><span class="parenthesis">(</span><span class="item-name">attributes</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_model.js.html#line14" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attributes</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Initial values for this model's attributes.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">tableName</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Initial value for <a href="api.html#Model-instance-tableName"><code>tableName</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">hasTimestamps</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Initial value for <a href="api.html#Model-instance-hasTimestamps"><code>hasTimestamps</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">parse</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Convert attributes by <a href="api.html#Model-instance-parse"><code>parse</code></a> before being <a href="api.html#Model-instance-set"><code>set</code></a> on the model.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>When defining a model you should use the <a href="api.html#Bookshelf-instance-model"><code>bookshelf.model</code></a> method, since it will allow you to
avoid circular dependency problems. However, it's still possible to create models using the regular constructor.</p>
<p>When creating an instance of a model, you can pass in the initial values of
the attributes, which will be <a href="api.html#Model-instance-set"><code>set</code></a> on the
model. If you define an <code>initialize</code> function, it will be invoked
when the model is created.</p>
<pre><code>new Book({
  title: &quot;One Thousand and One Nights&quot;,
  author: &quot;Scheherazade&quot;
});
</code></pre>
<p>In rare cases, if you're looking to get fancy, you may want to override
<code>constructor</code>, which allows you to replace the
actual constructor function for your model.</p>
<pre><code>let Book = bookshelf.model('Book', {
  tableName: 'documents',
  constructor: function() {
    bookshelf.Model.apply(this, arguments);
    this.on('saving', function(model, attrs, options) {
      options.query.where('type', '=', 'book');
    });
  }
});</code></pre>
    </div>
  
</div>

        
          
<div class="method has-description">
    

        <h4 id="Model-instance-initialize" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-initialize">initialize</a></span><span class="parenthesis">(</span><span class="item-name">attributes</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_model.js.html#line73" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attributes</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Initial values for this model's attributes.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>The hash of options passed to <a href="api.html#Model"><code>constructor</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Model">Model</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Called by the <a href="api.html#Model"><code>Model constructor</code></a> when creating a new instance.
Override this function to add custom initialization, such as event listeners.
Because plugins may override this method in subclasses, make sure to call
your super (extended) class.  e.g.</p>
<pre><code>initialize: function() {
    this.constructor.__super__.initialize.apply(this, arguments);
    // Your initialization code ...
}</code></pre>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    
        <h3 id="Model-subsection-static" class="subsection-title">Static</h3>
        <div class="statics">
          
              
<div class="method has-description">
    

        <h4 id="Model-static-collection" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-collection">collection</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">models</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_bookshelf.js.html#line227" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Customer.collection().fetch().then((customers) => {
  // ...
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">models</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
>
</span></code>
      

      <div class="description">
        <p>Any models to be added to the collection.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Additional options to pass to the <a href="api.html#Collection"><code>Collection</code></a> constructor.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">comparator</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>If specified this is used to sort the collection. It can be a string representing the
model attribute to sort by, or a custom function. Check the documentation for <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort">Array.prototype.sort</a> for more info on how to use a custom comparator function. If this
options is not specified the collection sort order depends on what the database returns.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>The newly created collection. It will be empty unless any models were passed as the first
argument.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>A simple static helper to instantiate a new <a href="api.html#Collection"><code>Collection</code></a>, setting the model it's
called on as the collection's target model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-static-count" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-count">count</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">column</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<number|string></span>
          <a href="lib_bookshelf.js.html#line253" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Duck.count().then((count) => {
  console.log('number of ducks', count)
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">column</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">'*'</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Specify a column to count. Rows with <code>null</code> values in this column will be excluded.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>0.8.2</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Model-instance-count">Model#count</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<number|string></code
>





        
  </div>

  
    <div class="item-description">
        <p>Shortcut to a model's <code>count</code> method so you don't need to instantiate a new model to count
the number of records.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-static-extend" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-extend">extend</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">prototypeProperties</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">classProperties</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  function</span>
          <a href="lib_base_model.js.html#line947" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Promise = require('bluebird')
const compare = require('some-crypt-library')

const Customer = bookshelf.model('Customer', {
  initialize() {
    this.constructor.__super__.initialize.apply(this, arguments)

    // Setting up a listener for the 'saving' event
    this.on('saving', this.validateSave)
  },

  validateSave() {
    return doValidation(this.attributes)
  },

  account() {
    // Defining a relation with the Account model
    return this.belongsTo(Account)
  }
}, {
  login: Promise.method(function(email, password) {
    if (!email || !password)
      throw new Error('Email and password are both required')

    return new this({email: email.toLowerCase()})
      .fetch()
      .tap(function(customer) {
        if (!compare(password, customer.get('password'))
          throw new Error('Invalid password')
      })
  })
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">prototypeProperties</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Instance methods and properties to be attached to instances of the new class.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">classProperties</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Class (i.e. static) functions and properties to be attached to the constructor of the new class.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >function</code
>




<span class="param-desc">
  <p>Constructor for new Model subclass.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This static method allows you to create your own Model classes by extending <a href="api.html#Model"><code>bookshelf.Model</code></a>.</p>
<p>It correctly sets up the prototype chain, which means that subclasses created this way can be further extended and
subclassed as far as you need.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-static-fetchAll" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-fetchAll">fetchAll</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Collection">Collection</a>></span>
          <a href="lib_bookshelf.js.html#line277" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Model-instance-fetchAll">Model#fetchAll</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Collection">Collection</a>></code
>





        
  </div>

  
    <div class="item-description">
        <p>Simple helper function for retrieving all instances of the given model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-static-forge" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-forge">forge</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">attributes</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_bookshelf.js.html#line205" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">attributes</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Initial values for this model's attributes.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">tableName</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Initial value for <a href="api.html#Model-instance-tableName"><code>tableName</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">hasTimestamps</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Initial value for <a href="api.html#Model-instance-hasTimestamps"><code>hasTimestamps</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">parse</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Convert attributes by <a href="api.html#Model-instance-parse"><code>parse</code></a> before being
<a href="api.html#Model-instance-set"><code>set</code></a> on the <code>model</code>.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>A simple helper function to instantiate a new Model without needing <code>new</code>.</p>
    </div>
  
</div>

          
        </div>
    

    
        <h3
          id="Model-subsection-members"
          class="subsection-title"
        >Members</h3>
        
            
<div class="method has-description">
    

        <h4 id="Model-instance-defaults" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-defaults">defaults</a></span><span class="type-signature"> :Object|Null</span>
          <a href="lib_base_model.js.html#line183" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var MyModel = bookshelf.model('MyModel', {
  defaults: {property1: 'foo', property2: 'bar'},
  tableName: 'my_models'
})

MyModel.forge({property1: 'blah'}).save().then(function(model) {
  // {property1: 'blah', property2: 'bar'}
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>This can be used to define any default values for attributes that are not
present when creating or updating a model in a <a href="api.html#Model-instance-save"><code>save</code></a> call.
The default behavior is to <em>not</em> use these default values on updates unless
the <code>defaults: true</code> option is passed to the <a href="api.html#Model-instance-save"><code>save</code></a> call.
For inserts the default values will always be used if present.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-hasTimestamps" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-hasTimestamps">hasTimestamps</a></span><span class="type-signature"> :Boolean|Array</span>
          <a href="lib_base_model.js.html#line262" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var MyModel = bookshelf.model('MyModel', {
  hasTimestamps: true,
  tableName: 'my_models'
})

var myModel = MyModel.forge({name: 'blah'}).save().then(function(savedModel) {
  // {
  //   name: 'blah',
  //   created_at: 'Sun Mar 25 2018 15:07:11 GMT+0100 (WEST)',
  //   updated_at: 'Sun Mar 25 2018 15:07:11 GMT+0100 (WEST)'
  // }
})

myModel.save({created_at: new Date(2015, 5, 2)}).then(function(updatedModel) {
  // {
  //   name: 'blah',
  //   created_at: 'Tue Jun 02 2015 00:00:00 GMT+0100 (WEST)',
  //   updated_at: 'Sun Mar 25 2018 15:07:11 GMT+0100 (WEST)'
  // }
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Automatically sets the current date and time on the timestamp attributes
<code>created_at</code> and <code>updated_at</code> based on the type of save method. The <em>update</em>
method will only update <code>updated_at</code>, while the <em>insert</em> method will set
both values.</p>
<p>To override the default attribute names, assign an array to this property.
The first element will be the <em>created</em> column name and the second will be
the <em>updated</em> one. If any of these elements is set to <code>null</code> that particular
timestamp attribute will not be used in the model. For example, to
automatically update only the <code>created_at</code> attribute set this property to
<code>['created_at', null]</code>.</p>
<p>You can override the timestamp attribute values of a model and those values
will be used instead of the automatic ones when saving.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-hidden" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-hidden">hidden</a></span><span class="type-signature"> :null|Array</span>
          <a href="lib_base_model.js.html#line299" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const MyModel = bookshelf.model('MyModel', {
  tableName: 'my_models',
  hidden: ['password']
})

const myModel = MyModel.forge({
  name: 'blah',
  password: 'secure'
}).save().then(function(savedModel) {
  console.log(savedModel.toJSON())
  // {
  //   name: 'blah',
  //   created_at: 'Sun Mar 25 2018 15:07:11 GMT+0100 (WEST)',
  //   updated_at: 'Sun Mar 25 2018 15:07:11 GMT+0100 (WEST)'
  // }
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>List of model attributes to exclude from the output when serializing it. This works as a
blacklist, and all attributes not present in this list will be shown when calling
<a href="api.html#Model-instance-toJSON"><code>toJSON</code></a>.</p>
<p>By default this is <code>null</code> which means that no attributes will be excluded from the output.</p>
<p>You can override this list by passing the <code>{hidden: ['list']}</code> option directly to the
<a href="api.html#Model-instance-toJSON"><code>toJSON</code></a> or <a href="api.html#Model-instance-serialize"><code>serialize</code></a> call.</p>
<p>If both the <code>hidden</code> and the <a href="api.html#Model-instance-visible"><code>visible</code></a> model properties are set, the
<code>hidden</code> list will take precedence.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-id" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-id">id</a></span><span class="type-signature"> :number|string</span>
          <a href="lib_base_model.js.html#line135" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Television = bookshelf.model('Television', {
  tableName: 'televisions',
  idAttribute: 'coolId'
})

new Television({coolId: 1}).fetch(tv => {
  tv.get('coolId') // 1
  tv.id // 1
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>A special property of models which represents their unique identifier, named by the
<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>. If you set the <code>id</code> in the attributes hash,
it will be copied onto the model as a direct property.</p>
<p>Models can be retrieved by their id from collections, and the id is used when fetching
models and building model relations.</p>
<p>Note that a model's <code>id</code> property can always be accessed even when the value of its
<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a> is not <code>'id'</code>.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-idAttribute" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-idAttribute">idAttribute</a></span><span class="type-signature"> :string</span>
          <a href="lib_base_model.js.html#line159" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>This tells the model which attribute to expect as the unique identifier
for each database row (typically an auto-incrementing primary key named
<code>'id'</code>). Note that if you are using <a href="api.html#Model-instance-parse"><code>parse</code></a> and <a href="api.html#Model-instance-format"><code>format</code></a> (to have your model's attributes in <code>camelCase</code>,
but your database's columns in <code>snake_case</code>, for example) this refers to
the name returned by parse (<code>myId</code>), not the actual database column
(<code>my_id</code>).</p>
<p>You can also get the parsed id attribute value by using the model's
<code>parsedIdAttribute</code> method.</p>
<p>If the table you're working with does not have a Primary-Key in the form
of a single column you'll have to override it with a getter that returns
<code>null</code>. Overriding with <code>undefined</code> does not cascade the default behavior of
the value <code>'id'</code>. Such a getter in ES6 would look like
<code>get idAttribute() { return null }</code>.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-requireFetch" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-requireFetch">requireFetch</a></span><span class="type-signature"> :boolean</span>
          <a href="lib_base_model.js.html#line217" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Default behavior
const MyModel = bookshelf.model('MyModel', {
  tableName: 'my_models'
})

new MyModel({id: 1}).fetch().catch(error => {
  // Will throw NotFoundError if there are no results
})

// Overriding the default behavior
const MyModel = bookshelf.model('MyModel', {
  requireFetch: false,
  tableName: 'my_models'
})

new MyModel({id: 1}).fetch(model => {
  // model will be null if there are no results
 })</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>1.0.0</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Allows defining the default behavior when there are no results when fetching a model from the
database. This applies only when fetching a single model using <a href="api.html#Model-instance-fetch"><code>fetch</code></a> or
<a href="api.html#Collection-instance-fetchOne"><code>Collection#fetchOne</code></a>.</p>
<p>You can override this model option when fetching by passing the <code>{require: false}</code> or
<code>{require: true}</code> option to any of the fetch methods mentioned above.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-tableName" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-tableName">tableName</a></span><span class="type-signature"> :string</span>
          <a href="lib_base_model.js.html#line96" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var Television = bookshelf.model('Television', {
  tableName: 'televisions'
});</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>A required property for any database usage, The
<a href="api.html#Model-instance-tableName"><code>tableName</code></a> property refers to the database
table name the model will query against.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-visible" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="name"><a href="api.html#Model-instance-visible">visible</a></span><span class="type-signature"> :null|Array</span>
          <a href="lib_base_model.js.html#line335" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const MyModel = bookshelf.model('MyModel', {
  tableName: 'my_models',
  visible: ['name', 'created_at']
})

const myModel = MyModel.forge({
  name: 'blah',
  password: 'secure'
}).save().then(function(savedModel) {
  console.log(savedModel.toJSON())
  // {
  //   name: 'blah',
  //   created_at: 'Sun Mar 25 2018 15:07:11 GMT+0100 (WEST)',
  // }
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>List of model attributes to include in the output when serializing it. This works as a
whitelist, and all attributes not present in this list will be hidden when calling
<a href="api.html#Model-instance-toJSON"><code>toJSON</code></a>.</p>
<p>By default this is <code>null</code> which means that all attributes will be included in the output.</p>
<p>You can override this list by passing the <code>{visible: ['list']}</code> option directly to the
<a href="api.html#Model-instance-toJSON"><code>toJSON</code></a> or <a href="api.html#Model-instance-serialize"><code>serialize</code></a> call.</p>
<p>If both the <a href="api.html#Model-instance-hidden"><code>hidden</code></a> and the <code>visible</code> model properties are set, the
<code>hidden</code> list will take precedence.</p>
    </div>
  
</div>

        
    

    
        <h3
          id="Model-subsection-methods"
          class="subsection-title"
        >Methods</h3>
        <div class="methods">
          
              
<div class="method has-description">
    

        <h4 id="Model-instance-belongsTo" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-belongsTo">belongsTo</a></span><span class="parenthesis">(</span><span class="item-name">Target</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line152" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Book = bookshelf.model('Book', {
  tableName: 'books',
  author() {
    return this.belongsTo('Author')
  }
})

// select * from `books` where id = 1
// select * from `authors` where id = book.author_id
Book.where({id: 1}).fetch({withRelated: ['author']}).then((book) => {
  console.log(JSON.stringify(book.related('author')))
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Target</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by the join. Can be a string specifying a previously registered model
with <a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in this model. By default, the <code>foreignKey</code> is assumed to be the singular form
of the <code>Target</code> model's tableName, followed by <code>_id</code>, or
<code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code> if the <code>idAttribute</code> property is set.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in the <code>Target</code> model's table which <code>foreignKey</code> references. This is only needed in
case it's other than <code>Target</code> model's <code>id</code> / <code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The return value will always be a model, even if the relation doesn't exist, but in that
case the relation will be <code>null</code> when <a href="api.html#Model-instance-serialize"><code>serializing</code></a> the model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This relationship is used when a model is a member of another <code>Target</code> model.</p>
<p>It can be used in <a href="tutorial-one-to-one.html">One-to-one</a> associations as the inverse of a
<a href="api.html#Model-instance-hasOne"><code>hasOne</code></a>. It can also used in <a href="tutorial-one-to-many.html">One-to-many</a> associations as the
inverse of <a href="api.html#Model-instance-hasMany"><code>hasMany</code></a>, and is the &quot;one&quot; side of that association. In both
cases, the belongsTo relationship is used for a model that is a member of another Target
model, referenced by the <code>foreignKey</code> attribute in the current model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-belongsToMany" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-belongsToMany">belongsToMany</a></span><span class="parenthesis">(</span><span class="item-name">Target</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">joinTableName</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">otherKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">otherKeyTarget</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_model.js.html#line197" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Account = bookshelf.model('Account', {
  tableName: 'accounts'
})

const User = bookshelf.model('User', {
  tableName: 'users',
  allAccounts() {
    return this.belongsToMany('Account')
  },
  adminAccounts() {
    return this.belongsToMany('Account').query({where: {access: 'admin'}})
  },
  viewAccounts() {
    return this.belongsToMany('Account').query({where: {access: 'readonly'}})
  }
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Target</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by join. Can be a string specifying a previously registered model with
<a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">joinTableName</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Name of the joining table. Defaults to the two table names ordered alphabetically and
joined by an underscore.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in this model. By default, the <code>foreignKey</code> is assumed to be the singular form
of this model's tableName, followed by <code>_id</code> / <code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">otherKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in the <code>Target</code> model. By default, this is assumed to be the singular form of
the <code>Target</code> model's tableName, followed by <code>_id</code> /
<code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in this model's table which <code>foreignKey</code> references. This is only needed if it's not
the default <code>id</code> / <code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">otherKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in the <code>Target</code> model's table which <code>otherKey</code> references. This is only needed, if
it's not the expected default of the <code>Target</code> model's <code>id</code> /
<code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>A new empty collection that is decorated with extra pivot helper methods. See the
description below for more info.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Defines a many-to-many relation, where the current model is joined to one or more of a
<code>Target</code> model through another table. The default name for the joining table is the two
models' table names joined by an underscore, and ordered alphabetically. For example, a
<code>users</code> table and an <code>accounts</code> table would have a joining table named <code>accounts_users</code>.</p>
<p>The default key names in the joining table are the singular versions of the model table
names, followed by <code>_id</code> / <code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>. So in the above
example the columns in the joining table would be <code>user_id</code>, <code>account_id</code>, and <code>access</code>,
which is used as an example of how dynamic relations can be formed using different contexts.</p>
<p>To customize the keys or the <a href="api.html#Model-instance-tableName"><code>tableName</code></a> used for the join table, you
may specify them in the arguments to the function call:</p>
<pre><code>this.belongsToMany(Account, 'users_accounts', 'userId', 'accountId')
</code></pre>
<p>If you wish to create a belongsToMany association where the joining table has a primary key
and extra attributes in the model, you may create a <code>belongsToMany</code>
<a href="api.html#Relation-instance-through"><code>through</code></a> relation:</p>
<pre><code>const Doctor = bookshelf.model('Doctor', {
  patients() {
    return this.belongsToMany('Patient').through('Appointment')
  }
})

const Appointment = bookshelf.model('Appointment', {
  patient() {
    return this.belongsTo('Patient')
  },
  doctor() {
    return this.belongsTo('Doctor')
  }
})

const Patient = bookshelf.model('Patient', {
  doctors() {
    return this.belongsToMany('Doctor').through('Appointment')
  }
})
</code></pre>
<p>Collections returned by a <code>belongsToMany</code> relation are decorated with several pivot helper
methods. If you need more information about these methods see
<a href="api.html#Collection-instance-attach"><code>attach</code></a>, <a href="api.html#Collection-instance-detach"><code>detach</code></a>,
<a href="api.html#Collection-instance-updatePivot"><code>updatePivot</code></a> and <a href="api.html#Collection-instance-withPivot"><code>withPivot</code></a>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-clear" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-clear">clear</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_base_model.js.html#line644" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>This model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Clear all attributes on the model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-clone" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-clone">clone</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_base_model.js.html#line707" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>Cloned instance of this model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns a new instance of the model with identical <code>attributes</code>, including any relations from the cloned
model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-count" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-count">count</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">column</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<number|string></span>
          <a href="lib_model.js.html#line772" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>new Duck().where('color', 'blue').count('name').then((count) => {
  console.log('number of blue ducks', count)
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">column</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">'*'</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Specify a column to count. Rows with <code>null</code> values in this column will be excluded.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>0.8.2</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    
    <h5>Fires</h5>
    <ul class="fired-event-list">
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-counting">"counting"</a></code>
        </li>
      
    </ul>
    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<number|string></code
>




<span class="param-desc">
  <p>A promise resolving to the number of matching rows. By default this will be a number,
except with PostgreSQL where it will be a string. Check the description to see how to
return a number instead in this case.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Gets the number of matching records in the database, respecting any previous calls to
<a href="api.html#Model-instance-query"><code>Model#query</code></a>. If the <code>column</code> argument is provided, records with a <code>null</code> value in
that column will be excluded from the count.</p>
<p><strong>Note</strong> that in PostgreSQL the result is a string by default. To read more about the
reasons for this see the <a href="https://github.com/brianc/node-postgres/pull/353">pull request</a>
that implemented it in the <code>node-postgres</code> database driver. If you're sure that the
results will always be less than 2<sup>53</sup> (9007199254740991) you can override
the default string parser like this:</p>
<pre><code>require('pg').defaults.parseInt8 = true
</code></pre>
<p>Put this snippet before the call to <code>require('knex')</code> wherever you are initalizing
<code>knex</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-destroy" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-destroy">destroy</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Model">Model</a>></span>
          <a href="lib_model.js.html#line1241" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>new User({id: 1})
  .destroy()
  .then(function(model) {
    // ...
  });</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Throw a <a href="api.html#Model-static-NoRowsDeletedError"><code>Model.NoRowsDeletedError</code></a> if no records are affected by destroy. This is
the default behavior as of version 0.13.0.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    
    <h5>Fires</h5>
    <ul class="fired-event-list">
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-destroying">"destroying"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-destroyed">"destroyed"</a></code>
        </li>
      
    </ul>
    

    

    

    
    <h5>Throws</h5>
    
            

  <code class="param-type"
  ><a href="api.html#Model-static-NoRowsDeletedError">Model.NoRowsDeletedError</a></code
>


<div class="param-desc">

</div>

        

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>></code
>




<span class="param-desc">
  <p>A promise resolving to the destroyed and thus
empty model, i.e. all attributes are <code>undefined</code>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p><code>destroy</code> performs a <code>delete</code> on the model, using the model's <a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a> to constrain the query.</p>
<p>A <a href="api.html#Model-event-destroying"><code>"destroying"</code></a> event is triggered on the model
before being destroyed. To prevent destroying the model, throwing an error
inside one of the event listeners will stop destroying the model and reject the
promise.</p>
<p>A <a href="api.html#Model-event-destroyed"><code>"destroyed"</code></a> event is fired after the model's
removal is completed.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-escape" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-escape">escape</a></span><span class="parenthesis">(</span><span class="item-name">attribute</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  string</span>
          <a href="lib_base_model.js.html#line571" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attribute</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The attribute to escape.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >string</code
>




<span class="param-desc">
  <p>HTML-escaped value of an attribute.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Get the HTML-escaped value of an attribute.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-fetch" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-fetch">fetch</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Model">Model</a>|null></span>
          <a href="lib_model.js.html#line613" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether or not to reject the returned response with a
<a href="api.html#Model-static-NotFoundError"><code>NotFoundError</code></a> if there are no results when
fetching. If set to <code>false</code> it will resolve with <code>null</code> instead.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">columns</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">'*'</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>Specify columns to be retrieved.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">lock</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Type of row-level lock to use. Valid options are <code>forShare</code> and
<code>forUpdate</code>. This only works in conjunction with the <code>transacting</code>
option, and requires a database that supports it.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">withRelated</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  >mixed[]</code
>
</span></code>
      

      <div class="description">
        <p>Relations to be retrieved with <code>Model</code> instance. Either one or more
relation names or objects mapping relation names to query callbacks.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    
    <h5>Fires</h5>
    <ul class="fired-event-list">
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-fetching">"fetching"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-fetched">"fetched"</a></code>
        </li>
      
    </ul>
    

    

    

    
    <h5>Throws</h5>
    
            

  <code class="param-type"
  ><a href="api.html#Model-static-NotFoundError">Model.NotFoundError</a></code
>


<div class="param-desc">

</div>

        

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>|null></code
>




<span class="param-desc">
  <p>A promise resolving to the fetched <a href="api.html#Model"><code>model</code></a> or <code>null</code> if
none exists and the <code>require: false</code> option is passed.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Fetches a <a href="api.html#Model"><code>model</code></a> from the database, using any <code>attributes</code> currently set on the model to constrain the
results.</p>
<p>A <a href="api.html#Model-event-fetching"><code>"fetching"</code></a> event will be fired just before the
record is fetched; a good place to hook into for validation. <a href="api.html#Model-event-fetched"><code>&quot;fetched&quot;</code></a> event will be fired when a record is
successfully retrieved.</p>
<p>If you need to constrain the query performed by fetch, you can call
<a href="api.html#Model-instance-query"><code>query</code></a> or <a href="api.html#Model-instance-where"><code>where</code></a> before calling
fetch.</p>
<pre><code>// select * from `books` where `ISBN-13` = '9780440180296'
new Book({'ISBN-13': '9780440180296'})
  .fetch()
  .then(function(model) {
    // outputs 'Slaughterhouse Five'
    console.log(model.get('title'));
  });
</code></pre>
<p>If you'd like to only fetch specific columns, you may specify a <code>columns</code>
property in the <code>options</code> for the fetch call, or use
<a href="api.html#Model-instance-query"><code>query</code></a>, tapping into the
<a href="https://knexjs.org/#Builder-column">Knex column</a> method to specify
which columns will be fetched.</p>
<p>A single property, or an array of properties can be specified as a value for
the <code>withRelated</code> property. You can also execute callbacks on relations
queries (eg. for sorting a relation). The results of these relation queries
will be loaded into a <code>relations</code> property on the
model, may be retrieved with the <a href="api.html#Model-instance-related"><code>related</code></a> method, and
will be serialized as properties on a <a href="api.html#Model-instance-toJSON"><code>toJSON</code></a> call
unless <code>{shallow: true}</code> is passed.</p>
<pre><code>let Book = bookshelf.model('Book', {
  tableName: 'books',
  editions: function() {
    return this.hasMany('Edition');
  },
  chapters: function() {
    return this.hasMany('Chapter');
  },
  genre: function() {
    return this.belongsTo('Genre');
  }
})

new Book({'ISBN-13': '9780440180296'}).fetch({
  withRelated: [
    'genre', 'editions',
    { chapters: function(query) { query.orderBy('chapter_number'); }}
  ]
}).then(function(book) {
  console.log(book.related('genre').toJSON());
  console.log(book.related('editions').toJSON());
  console.log(book.toJSON());
});</code></pre>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-fetchAll" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-fetchAll">fetchAll</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise</span>
          <a href="lib_model.js.html#line811" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Set of options to modify the request.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether or not to reject the returned Promise with a <a href="api.html#Collection-static-EmptyError"><code>Collection.EmptyError</code></a> if no records can be
fetched from the database.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    
    <h5>Fires</h5>
    <ul class="fired-event-list">
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-instance-fetching:collection">"fetching:collection"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-instance-fetched:collection">"fetched:collection"</a></code>
        </li>
      
    </ul>
    

    

    

    
    <h5>Throws</h5>
    
            

  <code class="param-type"
  ><a href="api.html#Collection-static-EmptyError">Collection.EmptyError</a></code
>


<div class="param-desc">

    <p>This error is used to reject the Promise in the event of an empty response from the
database in case the <code>require: true</code> fetch option is used.</p>

</div>

        

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>A Promise resolving to the fetched <a href="api.html#Collection"><code>collection</code></a>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Fetches a collection of <a href="api.html#Model"><code>models</code></a> from the database, using any
query parameters currently set on the model to constrain the results.</p>
<p>Returns a Promise that will resolve with the fetched collection. If there
are no results it will resolve with an empty collection. If instead you
wish the Promise to be rejected with a <a href="api.html#Collection-static-EmptyError"><code>Collection.EmptyError</code></a>,
pass the <code>require: true</code> option.</p>
<p>If you need to constrain the results, you can call the <a href="api.html#Model-instance-query"><code>query</code></a>
or <a href="api.html#Model-instance-where"><code>where</code></a> methods before calling this method.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-fetchPage" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-fetchPage">fetchPage</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Collection">Collection</a>></span>
          <a href="lib_model.js.html#line549" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>new Car()
  .fetchPage({
    pageSize: 15, // Defaults to 10 if not specified
    page: 3, // Defaults to 1 if not specified
    withRelated: ['engine'] // Passed to Model#fetchAll
  })
  .then(function(results) {
    console.log(results) // Paginated results object with metadata example below
  })

// Pagination results:
{
  models: [
    // Regular bookshelf Collection
  ],
  // other standard Collection attributes
  // ...
  pagination: {
    rowCount: 53, // Total number of rows found for the query before pagination
    pageCount: 4, // Total number of pages of results
    page: 3, // The requested page number
    pageSize: 15 // The requested number of rows per page
   }
}</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Besides the basic options that can be passed to <a href="api.html#Model-instance-fetchAll"><code>Model#fetchAll</code></a>, there are some additional pagination
options that can be specified.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">pageSize</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >number</code
>
</span></code>
      

      <div class="description">
        <p>How many models to include in each page, defaulting to 10 if not specified. Used only together with the <code>page</code>
option.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">page</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >number</code
>
</span></code>
      

      <div class="description">
        <p>Page number to retrieve. If greater than the available rows it will return an empty Collection. The first page
is number <code>1</code>. Used only with the <code>pageSize</code> option.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">limit</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >number</code
>
</span></code>
      

      <div class="description">
        <p>How many models to include in each page, defaulting to 10 if not specified. Used only together with the
<code>offset</code> option.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">offset</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >number</code
>
</span></code>
      

      <div class="description">
        <p>Index to begin fetching results from. The default and initial value is <code>0</code>. Used only with the <code>limit</code> option.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">disableCount</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to disable the query for counting how many records are in the full result.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Collection">Collection</a>></code
>




<span class="param-desc">
  <p>Returns a Promise that will resolve to the paginated collection of models.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This method is similar to <a href="api.html#Model-instance-fetchAll"><code>Model#fetchAll</code></a>, but fetches a single page of results as
specified by the limit (page size) and offset (page number).</p>
<p>Any options that may be passed to <a href="api.html#Model-instance-fetchAll"><code>Model#fetchAll</code></a> may also be passed in the options
to this method. Additionally, to perform pagination, you may include <strong>either</strong> an <code>offset</code>
and <code>limit</code>, <strong>or</strong> a <code>page</code> and <code>pageSize</code>.</p>
<p>By default, with no parameters or some missing parameters, <code>fetchPage</code> will use default
values of <code>{page: 1, pageSize: 10}</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-format" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-format">format</a></span><span class="parenthesis">(</span><span class="item-name">attributes</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Object</span>
          <a href="lib_base_model.js.html#line672" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attributes</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>The attributes to be converted.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Object</code
>




<span class="param-desc">
  <p>Formatted attributes.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The <code>format</code> method is used to modify the current state of the model before
it is persisted to the database. The <code>attributes</code> passed are a shallow clone
of the <a href="api.html#Model"><code>model</code></a>, and are only used for inserting/updating - the
current values of the model are left intact.</p>
<p>Do note that <code>format</code> is used to modify the state of the model when
accessing the database, so if you remove an attribute in your <code>format</code>
method, that attribute will never be persisted to the database, but it will
also never be used when doing a <code>fetch()</code>, which may cause unexpected
results. You should be very cautious with implementations of this method
that may remove the primary key from the list of attributes.</p>
<p>If you need to modify the database data before it is given to the model,
override the <a href="api.html#Model-instance-parse"><code>parse</code></a> method instead. That method does the
opposite operation of <code>format</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-get" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-get">get</a></span><span class="parenthesis">(</span><span class="item-name">attribute</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  mixed</span>
          <a href="lib_base_model.js.html#line370" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>note.get("title");</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attribute</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the attribute to retrieve.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >mixed</code
>




<span class="param-desc">
  <p>Attribute value.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Get the current value of an attribute from the model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-has" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-has">has</a></span><span class="parenthesis">(</span><span class="item-name">attribute</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Boolean</span>
          <a href="lib_base_model.js.html#line582" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attribute</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The attribute to check.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Boolean</code
>




<span class="param-desc">
  <p>True if <code>attribute</code> is set, otherwise <code>false</code>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns <code>true</code> if the attribute contains a value that is not null or undefined.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-hasChanged" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-hasChanged">hasChanged</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">attribute</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Boolean</span>
          <a href="lib_base_model.js.html#line835" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Author.forge({id: 1}).fetch().then(function(author) {
  author.hasChanged() // false
  author.set('name', 'Bob')
  author.hasChanged('name') // true
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">attribute</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>A specific attribute to check for changes.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Boolean</code
>




<span class="param-desc">
  <p><code>true</code> if any attribute has changed, <code>false</code> otherwise. Alternatively, if
the <code>attribute</code> argument was specified, checks if that particular
attribute has changed.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns <code>true</code> if any <code>attribute</code> has changed since
the last <a href="api.html#Model-instance-fetch"><code>fetch</code></a> or <a href="api.html#Model-instance-save"><code>save</code></a>. If an
attribute name is passed as argument, returns <code>true</code> only if that specific
attribute has changed.</p>
<p>Note that even if an attribute is changed by using the <a href="api.html#Model-instance-set"><code>set</code></a>
method, but the new value is exactly the same as the existing one, the
attribute is not considered <em>changed</em>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-hasMany" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-hasMany">hasMany</a></span><span class="parenthesis">(</span><span class="item-name">Target</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_model.js.html#line115" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Author = bookshelf.model('Author', {
  tableName: 'authors',
  books() {
    return this.hasMany('Book')
  }
})

// select * from `authors` where id = 1
// select * from `books` where author_id = 1
Author.where({id: 1}).fetch({withRelated: ['books']}).then(function(author) {
  console.log(JSON.stringify(author.related('books')))
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Target</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by join. Can be a string specifying a previously registered model with
<a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>ForeignKey in the <code>Target</code> model. By default, the foreign key is assumed to be the singular form of this
model's tableName, followed by <code>_id</code> / <code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in this model's table which <code>foreignKey</code> references, if other than this model's <code>id</code> /
<code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>A new empty Collection.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This relation specifies that this model has one or more rows in another table which match on this model's primary
key.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-hasOne" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-hasOne">hasOne</a></span><span class="parenthesis">(</span><span class="item-name">Target</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line68" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Record = bookshelf.model('Record', {
  tableName: 'health_records'
})

const Patient = bookshelf.model('Patient', {
  tableName: 'patients',
  record() {
    return this.hasOne('Record')
  }
})

// select * from `health_records` where `patient_id` = 1
new Patient({id: 1}).related('record').fetch().then(function(model) {
  // ...
})

// Alternatively, if you don't need the relation loaded on the patient's relations hash:
new Patient({id: 1}).record().fetch().then(function(model) {
  // ...
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Target</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by join. Can be a string specifying a previously registered model with
<a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in the <code>Target</code> model. By default the foreign key is assumed to be the singular form of this
model's <a href="api.html#Model-instance-tableName"><code>tableName</code></a> followed by <code>_id</code> / <code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">foreignKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in this model's table which <code>foreignKey</code> references, if other than this model's <code>id</code> /
<code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The return value will always be a model, even if the relation doesn't exist, but in that case the relation will
be <code>null</code> when <a href="api.html#Model-instance-serialize"><code>serializing</code></a> the model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This relation specifies that this table has exactly one of another type of object, specified by a foreign key in
the other table.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-isNew" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-isNew">isNew</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_model.js.html#line471" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var modelA = new bookshelf.Model();
modelA.isNew(); // true

var modelB = new bookshelf.Model({id: 1});
modelB.isNew(); // false</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Checks for the existence of an id to determine whether the model is
considered &quot;new&quot;.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-load" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-load">load</a></span><span class="parenthesis">(</span><span class="item-name">relations</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Model">Model</a>></span>
          <a href="lib_model.js.html#line881" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Using an array of strings with relation names
new Posts().fetch().then(function(collection) {
  return collection.at(0).load(['author', 'content', 'comments.tags'])
}).then(function(model) {
  JSON.stringify(model)

  // {
  //   title: 'post title',
  //   author: {...},
  //   content: {...},
  //   comments: [
  //     {tags: [...]}, {tags: [...]}
  //   ]
  // }
})

// Using an object with query callbacks to filter the relations
new Posts().fetch().then(function(collection) {
  return collection.at(0).load({comments: function(qb) {
    qb.where('comments.is_approved', '=', true)
  }})
}).then(function(model) {
  JSON.stringify(model)
  // the model now includes all approved comments
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">relations</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  >mixed[]</code
>
</span></code>
      

      <div class="description">
        <p>The relation, or relations, to be loaded.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">lock</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Type of row-level lock to use. Valid options are <code>forShare</code> and <code>forUpdate</code>. This only works in conjunction
with the <code>transacting</code> option, and requires a database that supports it.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>></code
>




<span class="param-desc">
  <p>A promise resolving to this <a href="api.html#Model"><code>model</code></a>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The load method takes an array of relations to eager load attributes onto a <a href="api.html#Model"><code>Model</code></a>, in a similar way that
the <code>withRelated</code> option works on <a href="api.html#Model-instance-fetch"><code>fetch</code></a>. Dot separated attributes may be used to specify deep
eager loading.</p>
<p>It is possible to pass an object with query callbacks to filter the relations to eager load. An example is
presented above.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-morphMany" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-morphMany">morphMany</a></span><span class="parenthesis">(</span><span class="item-name">Target</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">name</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">columnNames</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">morphValue</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_model.js.html#line343" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Target</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by join. Can be a string specifying a previously registered model with
<a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">name</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Prefix for <code>_id</code> and <code>_type</code> columns.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">columnNames</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>Array containing two column names, the first is the <code>_type</code> while the second is the <code>_id</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">morphValue</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">Target#<a href="api.html#Model-instance-tableName"><code>tablename</code></a></span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The string value associated with this relationship. Stored in the <code>_type</code> column of the polymorphic table.
Defaults to <code>Target</code>#<a href="api.html#Model-instance-tableName"><code>tablename</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>A collection of related models.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p><a href="api.html#Model-instance-morphMany"><code>morphMany</code></a> is essentially the same as a <a href="api.html#Model-instance-morphOne"><code>morphOne</code></a>, but creating a <a href="api.html#Collection"><code>collection</code></a>
rather than a <a href="api.html#Model"><code>model</code></a> (similar to a <a href="api.html#Model-instance-hasOne"><code>hasOne</code></a> vs. <a href="api.html#Model-instance-hasMany"><code>hasMany</code></a> relation).</p>
<p><a href="api.html#Model-instance-morphMany"><code>morphMany</code></a> is used to signify a <code>one-to-many</code> or <code>many-to-many</code> <code>polymorphic relation</code> with another <code>Target</code> model, where the <code>name</code> of the
model is used to determine which database table keys are used. The naming
convention requires the <code>name</code> prefix an <code>_id</code> and <code>_type</code> field in the
database. So for the case below the table names would be <code>imageable_type</code>
and <code>imageable_id</code>. The <code>morphValue</code> may be optionally set to
store/retrieve a different value in the <code>_type</code> column than the <code>Target</code>'s
<a href="api.html#Model-instance-tableName"><code>tableName</code></a>.</p>
<pre><code>let Post = bookshelf.model('Post', {
  tableName: 'posts',
  photos: function() {
    return this.morphMany('Photo', 'imageable');
  }
});
</code></pre>
<p>And with custom columnNames:</p>
<pre><code>let Post = bookshelf.model('Post'{
  tableName: 'posts',
  photos: function() {
    return this.morphMany('Photo', 'imageable', ['ImageableType', 'ImageableId']);
  }
});</code></pre>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-morphOne" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-morphOne">morphOne</a></span><span class="parenthesis">(</span><span class="item-name">Target</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">name</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">columnNames</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">morphValue</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line296" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Target</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by join. Can be a string specifying a previously registered model with
<a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">name</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Prefix for <code>_id</code> and <code>_type</code> columns.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">columnNames</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>Array containing two column names, the first is the <code>_type</code> while the second is the <code>_id</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">morphValue</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">Target#<a href="api.html#Model-instance-tableName"><code>tableName</code></a></span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The string value associated with this relationship. Stored in the <code>_type</code> column of the polymorphic table.
Defaults to <code>Target#<a href="api.html#Model-instance-tableName"><code>tableName</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The related model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The <a href="api.html#Model-instance-morphOne"><code>morphOne</code></a> is used to signify a <code>one-to-one</code> <code>polymorphic relation</code> with
another <code>Target</code> model, where the <code>name</code> of the model is used to determine
which database table keys are used. The naming convention requires the
<code>name</code> prefix an <code>_id</code> and <code>_type</code> field in the database. So for the case
below the table names would be <code>imageable_type</code> and <code>imageable_id</code>. The
<code>morphValue</code> may be optionally set to store/retrieve a different value in
the <code>_type</code> column than the <a href="api.html#Model-instance-tableName"><code>Model#tableName</code></a>.</p>
<pre><code>let Site = bookshelf.model('Site', {
  tableName: 'sites',
  photo: function() {
    return this.morphOne('Photo', 'imageable');
  }
});
</code></pre>
<p>And with custom <code>columnNames</code>:</p>
<pre><code>let Site = bookshelf.model('Site', {
  tableName: 'sites',
  photo: function() {
    return this.morphOne('Photo', 'imageable', ['ImageableType', 'ImageableId']);
  }
});
</code></pre>
<p>Note that both <code>columnNames</code> and <code>morphValue</code> are optional arguments. How
your argument is treated when only one is specified, depends on the type.
If your argument is an array, it will be assumed to contain custom
<code>columnNames</code>. If it's not, it will be assumed to indicate a <code>morphValue</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-morphTo" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-morphTo">morphTo</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">columnNames</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">Target</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line391" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Prefix for <code>_id</code> and <code>_type</code> columns.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">columnNames</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>Array containing two column names, where the first is the <code>_type</code> and the second is the <code>_id</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">Target</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Constructor of <a href="api.html#Model"><code>Model</code></a> targeted by join. Can be a string specifying a previously registered model with
<a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The related but empty model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This relation is used to specify the inverse of the <a href="api.html#Model-instance-morphOne"><code>morphOne</code></a> or
<a href="api.html#Model-instance-morphMany"><code>morphMany</code></a> relations, where the <code>targets</code> must be passed to signify which
<a href="api.html#Model"><code>models</code></a> are the potential opposite end of the <code>polymorphic relation</code>:</p>
<pre><code>const Photo = bookshelf.model('Photo', {
  tableName: 'photos',
  imageable() {
    return this.morphTo('imageable', 'Site', 'Post')
  }
})
</code></pre>
<p>And with custom column names:</p>
<pre><code>const Photo = bookshelf.model('Photo', {
  tableName: 'photos',
  imageable() {
    return this.morphTo('imageable', ['ImageableType', 'ImageableId'], 'Site', 'Post')
  }
})
</code></pre>
<p>And with custom morphValues, the inverse of the <code>morphValue</code> of <a href="api.html#Model-instance-morphOne"><code>morphOne</code></a> and
<a href="api.html#Model-instance-morphMany"><code>morphMany</code></a>, where the <code>morphValues</code> may be optionally set to check against a different
value in the <code>_type</code> column other than the <a href="api.html#Model-instance-tableName"><code>Model#tableName</code></a>, for example, a more descriptive name, or a
name that betters adheres to whatever standard you are using for models:</p>
<pre><code>const Photo = bookshelf.model('Photo', {
  tableName: 'photos',
  imageable() {
    return this.morphTo('imageable', ['Site', 'favicon'], ['Post', 'cover_photo'])
  }
})</code></pre>
    </div>
  
</div>

          
              
<div class="method no-description">
    

        <h4 id="Model-instance-off" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-off">off</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_model.js.html#line53" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>customer.off('fetched fetching');
ship.off(); // This will remove all event listeners</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Events-instance-off">Events#off</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-on" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-on">on</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_model.js.html#line42" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>customer.on('fetching', function(model) {
  // Do something before the data is fetched from the database
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Events-instance-on">Events#on</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Registers an event listener.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-once" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-once">once</a></span><span class="parenthesis">(</span><span class="item-name">nameOrNames</span><span class="comma">, </span><span class="item-name">callback</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_events.js.html#line104" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">nameOrNames</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the event or space separated list of events to register a
callback for.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">callback</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>That callback to invoke only once when the event is fired.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Just like <a href="api.html#Events-instance-on"><code>Events#on</code></a>, but causes the bound callback to fire only
once before being removed. Handy for saying &quot;the next time that X happens,
do this&quot;. When multiple events are passed in using the space separated
syntax, the event will fire once for every event you passed in, not once
for a combination of all events.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-orderBy" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-orderBy">orderBy</a></span><span class="parenthesis">(</span><span class="item-name">sort</span><span class="comma">, </span><span class="item-name">order</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_model.js.html#line1420" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Car.forge().orderBy('color', 'ASC').fetchAll()
   .then(function (rows) { // ...</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">sort</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column to sort on</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">order</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Ascending ('ASC') or descending ('DESC') order</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>0.9.3</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Specifies the column to sort on and sort order.</p>
<p>The order parameter is optional, and defaults to 'ASC'. You may
also specify 'DESC' order by prepending a hyphen to the sort column
name. <code>orderBy(&quot;date&quot;, 'DESC')</code> is the same as <code>orderBy(&quot;-date&quot;)</code>.</p>
<p>Unless specified using dot notation (i.e., &quot;table.column&quot;), the default
table will be the table name of the model <code>orderBy</code> was called on.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-parse" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-parse">parse</a></span><span class="parenthesis">(</span><span class="item-name">attributes</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Object</span>
          <a href="lib_base_model.js.html#line618" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Example of a parser to convert snake_case to camelCase, using lodash
// This is just an example. You can use the official case converter plugin
// to achieve the same functionality.
model.parse = function(attrs) {
  return _.mapKeys(attrs, function(value, key) {
    return _.camelCase(key);
  });
};</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attributes</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of attributes to parse.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Object</code
>




<span class="param-desc">
  <p>Parsed attributes.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The <code>parse</code> method is called whenever a <a href="api.html#Model"><code>model</code></a>'s data is
returned in a <a href="api.html#Model-instance-fetch"><code>fetch</code></a> call. The function is passed the raw
database response object, and should return the <code>attributes</code> hash to be <a href="api.html#Model-instance-set"><code>set</code></a> on the model. The default
implementation is a no-op, simply passing through the JSON response.
Override this if you need to format the database responses - for example
calling <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse">JSON.parse</a> on a text field containing JSON, or explicitly typecasting a
boolean in a sqlite3 database response.</p>
<p>If you need to format your data before it is saved to the database, override
the <a href="api.html#Model-instance-format"><code>format</code></a> method in your models. That method does the
opposite operation of <code>parse</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-previous" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-previous">previous</a></span><span class="parenthesis">(</span><span class="item-name">attribute</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  mixed</span>
          <a href="lib_base_model.js.html#line870" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Author.forge({id: 1}).fetch().then(function(author) {
  author.get('name') // Alice
  author.set('name', 'Bob')
  author.previous('name') // 'Alice'
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attribute</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The attribute to check.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >mixed</code
>




<span class="param-desc">
  <p>The previous value.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns the value of an attribute like it was before the last change. A
change is usually done with the <a href="api.html#Model-instance-set"><code>set</code></a> method, but it can
also be done with the <a href="api.html#Model-instance-save"><code>save</code></a> method. This is useful for
getting back the original attribute value after it's been changed. It can
also be used to get the original value after a model has been saved to the
database or destroyed.</p>
<p>In case you want to get the previous value of all attributes at once you
should use the <a href="api.html#Model-instance-previousAttributes"><code>previousAttributes</code></a> method.</p>
<p>Note that this will return <code>undefined</code> if the model hasn't been fetched,
saved, destroyed or eager loaded. However, in case one of these operations
did take place, it will return the current value if an attribute hasn't
changed. If you want to check if an attribute has changed see the
<a href="api.html#Model-instance-hasChanged"><code>hasChanged</code></a> method.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-previousAttributes" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-previousAttributes">previousAttributes</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Object</span>
          <a href="lib_base_model.js.html#line910" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Author.forge({id: 1}).fetch().then(function(author) {
  author.get('name') // Alice
  author.set('name', 'Bob')
  author.previousAttributes() // {id: 1, name: 'Alice'}
})

Author.forge({id: 1}).fetch().then(function(author) {
  author.get('name') // Alice
  return author.save({name: 'Bob'})
}).then(function(author) {
  author.get('name') // Bob
  author.previousAttributes() // {id: 1, name: 'Alice'}
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Object</code
>




<span class="param-desc">
  <p>The attributes as they were before the last change, or an empty object in
case the model data hasn't been fetched yet.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns a copy of the <a href="api.html#Model"><code>model</code></a>'s attributes like they were before
the last change. A change is usually done with the <a href="api.html#Model-instance-set"><code>set</code></a>
method, but it can also be done with the <a href="api.html#Model-instance-save"><code>save</code></a> method.
This is mostly useful for getting a diff of the model's attributes after
changing some of them. It can also be used to get the previous state of a
model after it has been saved to the database or destroyed.</p>
<p>In case you want to get the previous value of a single attribute you should
use the <a href="api.html#Model-instance-previous"><code>previous</code></a> method.</p>
<p>Note that this will return an empty object if no changes have been made to
the model and it hasn't been fetched, saved or eager loaded.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-query" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-query">query</a></span><span class="parenthesis">(</span><span class="item-name">arguments</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a>|QueryBuilder</span>
          <a href="lib_model.js.html#line1342" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>model
  .query('where', 'other_id', '=', '5')
  .fetch()
  .then(function(model) {
    // ...
  });

model
  .query({where: {other_id: '5'}, orWhere: {key: 'value'}})
  .fetch()
  .then(function(model) {
    // ...
  });

model.query(function(qb) {
  qb.where('other_person', 'LIKE', '%Demo').orWhere('other_id', '>', 10);
}).fetch()
  .then(function(model) {
    // ...
  });

let qb = model.query();
qb.where({id: 1}).select().then(function(resp) {
  // ...
});</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">arguments</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The query method.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="http://knexjs.org/#Builder">Knex `QueryBuilder`</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >QueryBuilder</code
>




<span class="param-desc">
  <p>Will return this model or, if called with no arguments, the underlying query builder.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The <code>query</code> method is used to tap into the underlying Knex query builder
instance for the current model. If called with no arguments, it will
return the query builder directly. Otherwise, it will call the specified
method on the query builder, applying any additional arguments from the
<code>model.query</code> call. If the method argument is a function, it will be
called with the Knex query builder as the context and the first argument,
returning the current model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-refresh" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-refresh">refresh</a></span><span class="parenthesis">(</span><span class="item-name">options</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Model">Model</a>></span>
          <a href="lib_model.js.html#line520" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>A hash of options. See <a href="api.html#Model-instance-fetch"><code>Model#fetch</code></a> for details.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>0.8.2</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>></code
>




<span class="param-desc">
  <p>A promise resolving to this model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Update the attributes of a model, fetching it by its primary key. If no
attribute matches its <a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>, then fetch by
all available fields.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-related" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-related">related</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a>|<a href="api.html#Collection">Collection</a>|undefined</span>
          <a href="lib_base_model.js.html#line694" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>new Photo({id: 1}).fetch({
  withRelated: ['account']
}).then(function(photo) {
  var account = photo.related('account') // Get the eagerly loaded account

  if (account.id) {
    // Fetch a relation that has not been eager loaded yet
    return account.related('trips').fetch()
  }
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the relation to retrieve.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
><code class="type-or">|</code><code class="param-type"
  >undefined</code
>




<span class="param-desc">
  <p>The specified relation as defined by a method on the model, or <code>undefined</code> if it does not exist.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This method returns a specified relation loaded on the relations hash on the model, or calls the associated relation
method and adds it to the relations hash if one exists and has not yet been loaded.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-resetQuery" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-resetQuery">resetQuery</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line1329" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Used to reset the internal state of the current query builder instance.
This method is called internally each time a database action is completed
by <code>Sync</code></p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-save" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-save">save</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">attrs</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Model">Model</a>></span>
          <a href="lib_model.js.html#line934" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// Save with no arguments
Model.forge({id: 5, firstName: 'John', lastName: 'Smith'}).save().then((model) => {
  //...
})

// Or add attributes during save
Model.forge({id: 5}).save({firstName: 'John', lastName: 'Smith'}).then((model) => {
  //...
})

// Or, if you prefer, for a single attribute
Model.forge({id: 5}).save('name', 'John Smith').then((model) => {
  //...
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">attrs</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Object containing the key: value pairs that you wish to save. If used with the <code>patch</code>
option only these values will be saved and any values already set on the model will be
ignored.</p>
<p>Instead of specifying this argument you can provide both a <code>key</code> and <code>value</code>
arguments to save a single value. This is demonstrated in the example.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">method</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Explicitly select a save method, either <code>&quot;update&quot;</code> or <code>&quot;insert&quot;</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">defaults</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to assign or not <a href="api.html#Model-instance-defaults"><code>default</code></a> attribute values
on a model when performing an update or create operation.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">patch</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Only save attributes supplied as arguments to the <code>save</code> call, ignoring any
attributes that may be already set on the model.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether or not to throw a <a href="api.html#Model-static-NoRowsUpdatedError"><code>Model.NoRowsUpdatedError</code></a> if no records
are affected by save.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">autoRefresh</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Weather to enable auto refresh such that after a model is saved it will be populated with all
the attributes that are present in the database, so you don't need to manually call
<a href="api.html#Model-instance-refresh"><code>refresh</code></a> to update it. This will use two queries unless
the database supports the <code>RETURNING</code> statement, in which case the model will
be saved and its data fetched with a single query.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    
    <h5>Fires</h5>
    <ul class="fired-event-list">
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-saving">"saving"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-creating">"creating"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-updating">"updating"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-created">"created"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-updated">"updated"</a></code>
        </li>
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Model-event-saved">"saved"</a></code>
        </li>
      
    </ul>
    

    

    

    
    <h5>Throws</h5>
    
            

  <code class="param-type"
  ><a href="api.html#Model-static-NoRowsUpdatedError">Model.NoRowsUpdatedError</a></code
>


<div class="param-desc">

</div>

        

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>></code
>




<span class="param-desc">
  <p>A promise resolving to the saved and updated model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This method is used to perform either an insert or update query using the
model's set <code>attributes</code>.</p>
<p>If the model <a href="api.html#Model-instance-isNew"><code>isNew</code></a>, any <a href="api.html#Model-instance-defaults"><code>defaults</code></a>
will be set and an <code>insert</code> query will be performed. Otherwise it will
<code>update</code> the record with a corresponding ID. It is also possible to
set default attributes on an <code>update</code> by passing the <code>{defaults: true}</code>
option in the second argument to the <code>save</code> call. This will also use the
same <a href="api.html#Model-instance-defaults"><code>defaults</code></a> as the <code>insert</code> operation.</p>
<p>The type of operation to perform (either <code>insert</code> or <code>update</code>) can be
overriden with the <code>method</code> option:</p>
<pre><code>// This forces an insert with the specified id instead of the expected update
new Post({name: 'New Article', id: 34})
  .save(null, {method: 'insert'})
  .then((model) =&gt; {
    // ...
  })
</code></pre>
<p>If you only wish to update with the params passed to the save, you may pass
a <code>{patch: true}</code> option in the second argument to <code>save</code>:</p>
<pre><code>// UPDATE authors SET &quot;bio&quot; = 'Short user bio' WHERE &quot;id&quot; = 1
new Author({id: 1, first_name: 'User'})
  .save({bio: 'Short user bio'}, {patch: true})
  .then((model) =&gt; {
    // ...
  })
</code></pre>
<p>Several events fire on the model when starting the save process:</p>
<ul>
<li><a href="api.html#Model-event-creating"><code>"creating"</code></a> if the model is being inserted.</li>
<li><a href="api.html#Model-event-updating"><code>"updating"</code></a> event if the model is being updated.</li>
<li><a href="api.html#Model-event-saving"><code>"saving"</code></a> event in either case.</li>
</ul>
<p>To prevent saving the model (for example, with validation), throwing an error
inside one of these event listeners will stop the save process and reject the
Promise.</p>
<p>If you wish to modify the query when the <a href="api.html#Model-event-saving"><code>"saving"</code></a>
event is fired, the <code>knex</code> query object is available in <code>options.query</code>.</p>
<p>After the save is complete the following events will fire:</p>
<ul>
<li><a href="api.html#Model-event-created"><code>"created"</code></a> if a new model was inserted in the
database</li>
<li><a href="api.html#Model-event-updated"><code>"updated"</code></a> if an existing model was updated.</li>
<li><a href="api.html#Model-event-saved"><code>"saved"</code></a> event either way.</li>
</ul>
<p>See the <a href="tutorial-events.html">Events</a> guide for further details.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-serialize" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-serialize">serialize</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Object</span>
          <a href="lib_base_model.js.html#line512" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var artist = new bookshelf.Model({
  firstName: "Wassily",
  lastName: "Kandinsky"
});

artist.set({birthday: "December 16, 1866"});

console.log(JSON.stringify(artist));
// {firstName: "Wassily", lastName: "Kandinsky", birthday: "December 16, 1866"}</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">shallow</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to exclude relations from the output or not.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">omitPivot</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to exclude pivot values from the output or not.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">hidden</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Array</code
>
</span></code>
      

      <div class="description">
        <p>List of model attributes to exclude from the output.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">visible</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Array</code
>
</span></code>
      

      <div class="description">
        <p>List of model attributes to include on the output. All other attributes will be hidden.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">visibility</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to use visibility options or not. If set to <code>false</code> the <code>hidden</code> and <code>visible</code> options
will be ignored.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Object</code
>




<span class="param-desc">
  <p>Serialized model as a plain object.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Return a copy of the model's <code>attributes</code> for JSON
stringification. If the <a href="api.html#Model"><code>model</code></a> has any relations defined, this
will also call <a href="api.html#Model-instance-toJSON"><code>toJSON</code></a> on each of the related
objects, and include them on the object unless <code>{shallow: true}</code> is
passed as an option.</p>
<p>You can define a whitelist of model attributes to include on the ouput with
the <code>{visible: ['list', 'of', 'attributes']}</code> option. The <code>{hidden: []}</code>
option produces the opposite effect, hiding attributes from the output.</p>
<p>This method is called internally by <a href="api.html#Model-instance-toJSON"><code>toJSON</code></a>. Override
this function if you want to customize its output.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-set" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-set">set</a></span><span class="parenthesis">(</span><span class="item-name">attribute</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">value</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_base_model.js.html#line417" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>customer.set({first_name: "Joe", last_name: "Customer"});
customer.set("telephone", "555-555-1212");</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attribute</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Attribute name, or hash of attribute names and values.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">value</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>If a string was provided for <code>attribute</code>, the value to be set.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">unset</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Remove attributes from the model instead of setting them.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>This model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Set a hash of attributes (one or many) on the model.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-through" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-through">through</a></span><span class="parenthesis">(</span><span class="item-name">Interim</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">throughForeignKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">otherKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">throughForeignKeyTarget</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">otherKeyTarget</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line454" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Chapter = bookshelf.model('Chapter', {
  tableName: 'chapters',
  paragraphs() {
    return this.hasMany('Paragraph')
  }
})
const Book = bookshelf.model('Book', {
  tableName: 'books',
  chapters() {
    return this.hasMany('Chapter')
  }
})

     const Paragraph = bookshelf.model('Paragraph', {
  tableName: 'paragraphs',
  chapter() {
    return this.belongsTo('Chapter')
  },

  // Find the book where this paragraph is included, by passing through
  // the "Chapter" model.
  book() {
    return this.belongsTo('Book').through('Chapter')
  }
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Interim</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Pivot model. Can be a string specifying a previously registered model with <a href="api.html#Bookshelf-instance-model"><code>Bookshelf#model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">throughForeignKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in this model. By default, the foreign key is assumed to be the singular form of the <code>Target</code>
model's tableName, followed by <code>_id</code> or <code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">otherKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in the <code>Interim</code> model. By default, the other key is assumed to be the singular form of this
model's tableName, followed by <code>_id</code> / <code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">throughForeignKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in the <code>Target</code> model which <code>throughForeignKey</code> references, if other than <code>Target</code> model's <code>id</code> /
<code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">otherKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in this model which <code>otherKey</code> references, if other than <code>id</code> / <code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The related but empty Model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Helps to create dynamic relations between <a href="api.html#Model"><code>models</code></a> where a <a href="api.html#Model-instance-hasOne"><code>hasOne</code></a> or
<a href="api.html#Model-instance-belongsTo"><code>belongsTo</code></a> relation may run through another <code>Interim</code> model. This is exactly like the
equivalent <a href="api.html#Collection-instance-through"><code>collection method</code></a> except that it applies to the models that the above
mentioned relation methods return instead of collections.</p>
<p>This method creates a pivot model, which it assigns to <code>model.pivot</code> after it is created. When
serializing the model with <a href="api.html#Model-instance-toJSON"><code>toJSON</code></a>, the pivot model is flattened to values prefixed with
<code>_pivot_</code>.</p>
<p>A good example of where this would be useful is if a paragraph <a href="api.html#Model-instance-hasMany"><code>belongsTo</code></a> a book <em>through</em> a
chapter. See the example above on how this can be expressed.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-timestamp" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-timestamp">timestamp</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Object</span>
          <a href="lib_base_model.js.html#line785" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">method</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Either <code>'insert'</code> or <code>'update'</code> to specify what kind of save the attribute
update is for.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">date</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Either a Date object or ms since the epoch. Specify what date is used for
updateing the timestamps, i.e. if something other than <code>new Date()</code> should be used.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Object</code
>




<span class="param-desc">
  <p>A hash of timestamp attributes that were set.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Automatically sets the timestamp attributes on the model, if
<a href="api.html#Model-instance-hasTimestamps"><code>hasTimestamps</code></a> is set to <code>true</code> or an array. It
checks if the model is new and sets the <code>created_at</code> and <code>updated_at</code>
attributes (or any other custom attribute names you have set) to the current
date. If the model is not new and is just being updated then only the
<code>updated_at</code> attribute gets automatically updated.</p>
<p>If the model contains any user defined <code>created_at</code> or <code>updated_at</code> values,
there won't be any automatic updated of these attributes and the user
supplied values will be used instead.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-toJSON" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-toJSON">toJSON</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_model.js.html#line552" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options passed to <a href="api.html#Model-instance-serialize"><code>Model#serialize</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Called automatically by <a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior"><code>JSON.stringify</code></a>. To customize serialization, override <a href="api.html#Model-instance-serialize"><code>serialize</code></a>.</p>
    </div>
  
</div>

          
              
<div class="method no-description">
    

        <h4 id="Model-instance-trigger" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-trigger">trigger</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_model.js.html#line63" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>ship.trigger('fetched');</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Events-instance-trigger">Events#trigger</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-triggerThen" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-triggerThen">triggerThen</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise</span>
          <a href="lib_base_events.js.html#line80" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The event name or a whitespace-separated list of event names to be triggered.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>Arguments to be passed to any registered event handlers.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>A promise resolving to the return values of any triggered handlers.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>A promise version of <a href="api.html#Events-instance-trigger"><code>Events#trigger</code></a>, returning a promise which
resolves with all return values from triggered event handlers. If any of the
event handlers throw an <code>Error</code> or return a rejected promise, the promise
will be rejected. Used internally on the <a href="api.html#Model-event-creating"><code>"creating"</code></a>,
<a href="api.html#Model-event-updating"><code>"updating"</code></a>, <a href="api.html#Model-event-saving"><code>"saving"</code></a>, and
<code>"destroying"</code> events, and can be helpful when needing
async event handlers (e.g. for validations).</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-unset" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-unset">unset</a></span><span class="parenthesis">(</span><span class="item-name">attribute</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_base_model.js.html#line635" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attribute</span></code>

      

      <div class="description">
        <p>Attribute to unset.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>This model.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Remove an attribute from the model. <code>unset</code> is a noop if the attribute
doesn't exist.</p>
<p>Note that unsetting an attribute from the model will not affect the related
record's column value when saving the model. In order to clear the value of a
column in the database record, set the attribute value to <code>null</code> instead:
<code>model.set(&quot;column_name&quot;, null)</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Model-instance-where" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-instance-where">where</a></span><span class="parenthesis">(</span><span class="item-name">method</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_model.js.html#line1390" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>model.where('favorite_color', '&lt;>', 'green').fetch().then(function() { //...
// or
model.where('favorite_color', 'red').fetch().then(function() { //...
// or
model.where({favorite_color: 'red', shoe_size: 12}).fetch().then(function() { //...</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">method</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Either <code>key, [operator], value</code> syntax, or a hash of attributes to
match. Note that these must be formatted as they are in the database,
not how they are stored after <a href="api.html#Model-instance-parse"><code>Model#parse</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Model-instance-query">Model#query</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The where method is used as convenience for the most common <a href="api.html#Model-instance-query"><code>query</code></a> method, adding a where clause to the builder. Any
additional knex methods may be accessed using <a href="api.html#Model-instance-query"><code>query</code></a>.</p>
<p>Accepts either key, value syntax, or a hash of attributes.</p>
    </div>
  
</div>

          
        </div>
    

    
        <h3
          id="Model-subsection-lodash-methods"
          class="subsection-title"
        >Lodash Methods</h3>
        <ul class="lodash-methods">
          
              <li id="Model-instance-omit" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#omit">omit</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Model-instance-pick" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#pick">pick</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
        </ul>
    

    

    
        <h3
          id="Model-subsection-events"
          class="subsection-title"
        >Events</h3>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-counting" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-counting">"counting"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_sync.js.html#line96" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-count"><code>count</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Counting event.</p>
<p>Fired before a <code>count</code> query. A promise may be
returned from the event handler for async behaviour.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-created" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-created">"created"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1210" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event with its attributes matching what's in the database.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-save"><code>save</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Created event.</p>
<p>Fired after an <code>insert</code> query.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-creating" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-creating">"creating"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">attrs</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1117" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">attrs</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Attributes that will be inserted.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-save"><code>save</code></a>.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">query</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >QueryBuilder</code
>
</span></code>
      

      <div class="description">
        <p>Query builder to be used for saving. This can be used to modify or add to the query
before it is executed.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Creating event.</p>
<p>Fired before an <code>insert</code> query. A Promise may be returned from the event handler for
async behaviour. Throwing an exception from the handler will cancel the save process.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-destroyed" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-destroyed">"destroyed"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1312" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-destroy"><code>destroy</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Destroyed event.</p>
<p>Fired after a <code>delete</code> query. A promise may be returned from the event
handler for async behaviour.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-destroying" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-destroying">"destroying"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1286" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-destroy"><code>destroy</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Destroying event.</p>
<p>Fired before a <code>delete</code> query. A promise may be returned from the event
handler for async behaviour. Throwing an exception from the handler
will reject the promise and cancel the deletion.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-fetched" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-fetched">"fetched"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">response</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line737" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">response</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Knex query response.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-fetch"><code>fetch</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>If the handler returns a promise, <code>fetch</code> will wait for it to
be resolved.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Fired after a <code>fetch</code> operation. A promise may be returned from the
event handler for async behaviour.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-fetching" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-fetching">"fetching"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">columns</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_sync.js.html#line179" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const MyModel = bookshelf.model('MyModel', {
  initialize() {
    this.on('fetching', function(model, columns, options) {
      options.query.where('status', 'active')
    })
  }
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model which is about to be fetched.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">columns</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>The columns to be retrieved by the query.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-fetch"><code>fetch</code></a>.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">query</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >QueryBuilder</code
>
</span></code>
      

      <div class="description">
        <p>Query builder to be used for fetching. This can be used to modify or add to the query
before it is executed. See example above.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Fired before a <code>fetch</code> operation. A promise may be returned from the event handler for
async behaviour.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-saved" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-saved">"saved"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1197" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event with its attributes matching what's in the database.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-save"><code>save</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Saved event.</p>
<p>Fired after an <code>insert</code> or <code>update</code> query.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-saving" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-saving">"saving"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">attrs</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1097" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event. Its attributes are already changed but not commited to
the database yet.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">attrs</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Attributes that will be inserted or updated.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-save"><code>save</code></a>.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">query</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >QueryBuilder</code
>
</span></code>
      

      <div class="description">
        <p>Query builder to be used for saving. This can be used to modify or add to the query
before it is executed.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Saving event.</p>
<p>Fired before an <code>insert</code> or <code>update</code> query. A Promise may be returned from the event
handler for async behaviour. Throwing an exception from the handler will cancel the
save process.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-updated" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-updated">"updated"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1223" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event with its attributes matching what's in the database.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-save"><code>save</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Updated event.</p>
<p>Fired after an <code>update</code> query.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-event-updating" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-event-updating">"updating"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">attrs</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line1134" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The model firing the event. Its attributes are already changed but not commited to
the database yet.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">attrs</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Attributes that will be updated.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-save"><code>save</code></a>.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">query</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >QueryBuilder</code
>
</span></code>
      

      <div class="description">
        <p>Query builder to be used for saving. This can be used to modify or add to the query
before it is executed.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Updating event.</p>
<p>Fired before an <code>update</code> query. A Promise may be returned from the event handler for
async behaviour. Throwing an exception from the handler will cancel the save process.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-fetched:collection" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-instance-fetched:collection">"fetched:collection"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">collection</span><span class="comma">, </span><span class="item-name">response</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line862" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">collection</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>
</span></code>
      

      <div class="description">
        <p>The collection that has been fetched.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">response</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>The raw response from the underlying query builder. This will be an array with objects
representing each row, similar to the output of a
<a href="api.html#Model-instance-serialize"><code>serialized Model</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-fetchAll"><code>fetchAll</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Fired after a <a href="api.html#Model-instance-fetchAll"><code>fetchAll</code></a> operation. A promise
may be returned from the event handler for async behaviour.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Model-instance-fetching:collection" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >model</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Model-instance-fetching:collection">"fetching:collection"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">collection</span><span class="comma">, </span><span class="item-name">columns</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_model.js.html#line843" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">collection</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>
</span></code>
      

      <div class="description">
        <p>The collection that is going to be fetched. At this point it's still empty since the
fetch hasn't happened yet.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">columns</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>The columns to be retrieved by the query as provided by the underlying query builder.
If the <code>columns</code> option is not specified the value of this will usually be an array
with a single string <code>'tableName.*'</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Model-instance-fetchAll"><code>fetchAll</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Fired before a <a href="api.html#Model-instance-fetchAll"><code>fetchAll</code></a> operation. A promise
may be returned from the event handler for async behaviour.</p>
    </div>
  
</div>

        
    
</article>


    





<article>
    
        <h2 id="section-Model-static-NoRowsDeletedError">
            <span class="ancestors"><a href="api.html#Model">Model</a>.</span
        >NoRowsDeletedError</h2>
        
    

    <div class="container-overview">
    
        <h3
          id="Model-static-NoRowsDeletedError-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Model-static-NoRowsDeletedError" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-NoRowsDeletedError">NoRowsDeletedError</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_model.js.html#line1548" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Thrown when no record is deleted by <a href="api.html#Model-instance-destroy"><code>destroy</code></a>
unless called with the <code>{require: false}</code> option.</p>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    

    

    

    

    

    
</article>











<article>
    
        <h2 id="section-Model-static-NoRowsUpdatedError">
            <span class="ancestors"><a href="api.html#Model">Model</a>.</span
        >NoRowsUpdatedError</h2>
        
    

    <div class="container-overview">
    
        <h3
          id="Model-static-NoRowsUpdatedError-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Model-static-NoRowsUpdatedError" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-NoRowsUpdatedError">NoRowsUpdatedError</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_model.js.html#line1540" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Thrown when no records are saved by <a href="api.html#Model-instance-save"><code>save</code></a>
unless called with the <code>{require: false}</code> option.</p>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    

    

    

    

    

    
</article>











<article>
    
        <h2 id="section-Model-static-NotFoundError">
            <span class="ancestors"><a href="api.html#Model">Model</a>.</span
        >NotFoundError</h2>
        
    

    <div class="container-overview">
    
        <h3
          id="Model-static-NotFoundError-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Model-static-NotFoundError" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Model</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Model-static-NotFoundError">NotFoundError</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_model.js.html#line1531" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Thrown when no records are found by <a href="api.html#Model-instance-fetch"><code>fetch</code></a> or
<a href="api.html#Model-instance-refresh"><code>refresh</code></a> unless called with the <code>{require: false}</code>
option.</p>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    

    

    

    

    

    
</article>

















<article>
    
        <h2 id="section-Collection">Collection</h2>
        
            <div class="class-description"><p>Collections are ordered sets of models returned from the database, from a
<a href="api.html#Model-instance-fetchAll"><code>fetchAll</code></a> call.</p></div>
        
    

    <div class="container-overview">
    
        <h3
          id="Collection-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Collection" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="parameters"><span class="name"><a href="api.html#Collection">Collection</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">models</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line10" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const TabSet = bookshelf.collection('TabSet', {
  model: Tab
})
const tabs = new TabSet([tab1, tab2, tab3])</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">models</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
>
</span></code>
      

      <div class="description">
        <p>Initial array of models.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">comparator</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p><code>Comparator</code> for collection, or <code>false</code> to disable sorting.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>When creating a <a href="api.html#Collection"><code>Collection</code></a>, you may choose to pass in the initial array of
<a href="api.html#Model"><code>models</code></a>. The collection's <code>comparator</code> may be included
as an option. Passing <code>false</code> as the comparator option will prevent sorting. If you define an
<a href="api.html#Collection-instance-initialize"><code>initialize</code></a> function, it will be invoked when the collection is
created.</p>
<p>If you would like to customize the Collection used by your models when calling
<a href="api.html#Model-instance-fetchAll"><code>Model#fetchAll</code></a> or <a href="api.html#Model-instance-fetchPage"><code>Model#fetchPage</code></a> you can use the following process:</p>
<pre><code>const Test = bookshelf.model('Test', {
  tableName: 'test'
}, {
  collection(...args) {
    return new Tests(...args)
  }
})
const Tests = bookshelf.collection('Tests', {
  get model() {
    return Test
  },
  initialize () {
    this.constructor.__super__.initialize.apply(this, arguments)
    // Collection will emit fetching event as expected even on eager queries.
    this.on('fetching', () =&gt; {})
  },
  doStuff() {
    // This method will be available in the results collection returned
    // by Test.fetchAll() and Test.fetchPage()
  }
})</code></pre>
    </div>
  
</div>

        
          
<div class="method has-description">
    

        <h4 id="Collection-instance-initialize" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-initialize">initialize</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line106" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Collection">Collection</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Called by the <a href="api.html#Collection"><code>Collection constructor</code></a> when creating a new instance.
Override this function to add custom initialization, such as event listeners.
Because plugins may override this method in subclasses, make sure to call
your super (extended) class. e.g.</p>
<pre><code>initialize: function() {
  this.constructor.__super__.initialize.apply(this, arguments);
  // Your initialization code ...
}</code></pre>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    
        <h3 id="Collection-subsection-static" class="subsection-title">Static</h3>
        <div class="statics">
          
              
<div class="method has-description">
    

        <h4 id="Collection-static-extend" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-static-extend">extend</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">prototypeProperties</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">classProperties</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  function</span>
          <a href="lib_base_collection.js.html#line785" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">prototypeProperties</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Instance methods and properties to be attached to instances of the new
class.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">classProperties</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Class (ie. static) functions and properties to be attached to the
constructor of the new class.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >function</code
>




<span class="param-desc">
  <p>Constructor for new <code>Collection</code> subclass.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>To create a <a href="api.html#Collection"><code>Collection</code></a> class of your own, extend
<code>Bookshelf.Collection</code>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-static-forge" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-static-forge">forge</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">models</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_bookshelf.js.html#line300" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var Promise = require('bluebird');
var Accounts = bookshelf.Collection.extend({
  model: Account
});

var accounts = Accounts.forge([
  {name: 'Person1'},
  {name: 'Person2'}
]);

Promise.all(accounts.invokeMap('save')).then(function() {
  // collection models should now be saved...
});</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">models</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object[]</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
>
</span></code>
      

      <div class="description">
        <p>Set of models (or attribute hashes) with which to initialize the
collection.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>A simple helper function to instantiate a new Collection without needing
new.</p>
    </div>
  
</div>

          
        </div>
    

    
        <h3
          id="Collection-subsection-members"
          class="subsection-title"
        >Members</h3>
        
            
<div class="method has-description">
    

        <h4 id="Collection-instance-count" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="name"><a href="api.html#Collection-instance-count">count</a></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line231" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// select count(*) from shareholders where company_id = 1 and share &amp;gt; 0.1;
new Company({id: 1})
  .shareholders()
  .where('share', '>', '0.1')
  .count()
  .then((count) => {
    assert(count === 3)
  })</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">column</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">'*'</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Specify a column to count. Rows with <code>null</code> values in this column will be excluded.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>0.8.2</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Model-instance-count">Model#count</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<number|string></code
>





        
  </div>

  
    <div class="item-description">
        <p>Get the number of records in the collection's table.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Collection-instance-create" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="name"><a href="api.html#Collection-instance-create">create</a></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line339" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const { courses, ...attributes } = req.body;

Student.forge(attributes).save().tap(student =>
  Promise.map(courses, course => student.related('courses').create(course))
).then(student =>
  res.status(200).send(student)
).catch(error =>
  res.status(500).send(error.message)
);</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>A set of attributes to be set on the new model.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>></code
>




<span class="param-desc">
  <p>A promise resolving with the new <a href="api.html#Model"><code>model</code></a>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Convenience method to create a new <a href="api.html#Model"><code>model</code></a> instance within a
collection. Equivalent to instantiating a model with a hash of <code>attributes</code>, <a href="api.html#Model-instance-save"><code>saving</code></a> the model to the
database then adding the model to the collection.</p>
<p>When used on a relation, <code>create</code> will automatically set foreign key
attributes before persisting the <code>Model</code>.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Collection-instance-fetch" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="name"><a href="api.html#Collection-instance-fetch">fetch</a></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line156" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether or not to throw a <a href="api.html#Collection-static-EmptyError"><code>Collection.EmptyError</code></a> if no records are found.
You can pass the <code>require: true</code> option to override this behavior.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">withRelated</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">[]</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>A relation, or list of relations, to be eager loaded as part of the <code>fetch</code> operation.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    
    <h5>Fires</h5>
    <ul class="fired-event-list">
      
        <li class="fired-event-item">
          <code class="event-name"><a href="api.html#Collection-event-fetched">"fetched"</a></code>
        </li>
      
    </ul>
    

    

    

    
    <h5>Throws</h5>
    
            

  <code class="param-type"
  ><a href="api.html#Collection-static-EmptyError">Collection.EmptyError</a></code
>


<div class="param-desc">

    <p>Thrown if no records are found.</p>

</div>

        

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Collection">Collection</a>></code
>





        
  </div>

  
    <div class="item-description">
        <p>Fetch the default set of models for this collection from the database,
resetting the collection when they arrive. If you wish to trigger an
error if the fetched collection is empty, pass <code>{require: true}</code> as one
of the options to the <a href="api.html#Collection-instance-fetch"><code>fetch</code></a> call. A <code>&quot;fetched&quot;</code> event will be fired when records are
successfully retrieved. If you need to constrain the query performed by
<code>fetch</code>, you can call the <a href="api.html#Collection-instance-query"><code>query</code></a> method before
calling <code>fetch</code>.</p>
<p>If you'd like to only fetch specific columns, you may specify a <code>columns</code>
property in the options for the <code>fetch</code> call.</p>
<p>The <code>withRelated</code> option may be specified to fetch the models of the
collection, eager loading any specified <a href="api.html#Relation"><code>relations</code></a> named on
the model. A single property, or an array of properties can be specified as
a value for the <code>withRelated</code> property. The results of these relation
queries will be loaded into a relations property on the respective models,
may be retrieved with the <a href="api.html#Model-instance-related"><code>related</code></a> method.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Collection-instance-fetchOne" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="name"><a href="api.html#Collection-instance-fetchOne">fetchOne</a></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line277" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>// select * from authors where site_id = 1 and id = 2 limit 1;
new Site({id:1})
  .authors()
  .query({where: {id: 2}})
  .fetchOne()
  .then(function(model) {
    // ...
  });</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether or not to reject the returned Promise with a <a href="api.html#Model-static-NotFoundError"><code>Model.NotFoundError</code></a> if no
records can be fetched from the database.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">columns</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">'*'</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>Limit the number of columns fetched.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">lock</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Type of row-level lock to use. Valid options are <code>forShare</code> and
<code>forUpdate</code>. This only works in conjunction with the <code>transacting</code>
option, and requires a database that supports it.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    
    <h5>Throws</h5>
    
            

  <code class="param-type"
  ><a href="api.html#Model-static-NotFoundError">Model.NotFoundError</a></code
>


<div class="param-desc">

</div>

        

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Model">Model</a>|null></code
>




<span class="param-desc">
  <p>A promise resolving to the fetched <a href="api.html#Model"><code>Model</code></a> or <code>null</code> if none exists and the
<code>require: false</code> option is passed or <a href="api.html#Model-instance-requireFetch"><code>requireFetch</code></a> is set to
<code>false</code>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Fetch and return a single <a href="api.html#Model"><code>model</code></a> from the collection,
maintaining any <a href="api.html#Relation"><code>relation</code></a> data from the collection, and
any <a href="api.html#Collection-instance-query"><code>query</code></a> parameters that have already been passed
to the collection. Especially helpful on relations, where you would only
like to return a single model from the associated collection.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Collection-instance-length" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="name"><a href="api.html#Collection-instance-length">length</a></span><span class="type-signature"> :Number</span>
          <a href="lib_base_collection.js.html#line104" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var vanHalen = new bookshelf.Collection([eddie, alex, stone, roth]);
console.log(vanHalen.length) // 4</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>This is the total number of models in the collection. Note that this may not represent how many
models there are in total in the database.</p>
    </div>
  
</div>

        
            
<div class="method has-description">
    

        <h4 id="Collection-instance-load" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="name"><a href="api.html#Collection-instance-load">load</a></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line302" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">relations</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
><code class="type-or">|</code><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>The relation, or relations, to be loaded.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">lock</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Type of row-level lock to use. Valid options are <code>forShare</code> and <code>forUpdate</code>. This only
works in conjunction with the <code>transacting</code> option, and requires a database that supports
it.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">debug</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >boolean</code
>
</span></code>
      

      <div class="description">
        <p>Whether to enable debugging mode or not. When enabled will show information about the
queries being run.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Collection">Collection</a>></code
>




<span class="param-desc">
  <p>A promise resolving to this <a href="api.html#Collection"><code>collection</code></a>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This method is used to eager load relations onto a Collection, in a similar way that the
<code>withRelated</code> property works on <a href="api.html#Collection-instance-fetch"><code>fetch</code></a>. Nested eager loads can be
specified by separating the nested relations with <code>.</code>.</p>
    </div>
  
</div>

        
    

    
        <h3
          id="Collection-subsection-methods"
          class="subsection-title"
        >Methods</h3>
        <div class="methods">
          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-add" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-add">add</a></span><span class="parenthesis">(</span><span class="item-name">models</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_base_collection.js.html#line455" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const ships = new bookshelf.Collection;

ships.add([
  {name: "Flying Dutchman"},
  {name: "Black Pearl"}
]);</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">models</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object[]</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>One or more models or raw attribute objects.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options for controlling how models are added.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">merge</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>If set to <code>true</code> it will merge the attributes of duplicate models with the
attributes of existing models in the collection.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">at</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Number</code
>
</span></code>
      

      <div class="description">
        <p>If set to a number equal to or greater than 0 it will splice the model
into the collection at the specified index number.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Add a <a href="api.html#Model"><code>model</code></a>, or an array of models, to the collection. You may
also pass raw attribute objects, which will be converted to proper models
when being added to the collection.</p>
<p>You can pass the <code>{at: index}</code> option to splice the model into the
collection at the specified <code>index</code>.</p>
<p>By default if you're adding models to the collection that are already
present, they'll be ignored, unless you pass <code>{merge: true}</code>, in
which case their <code>attributes</code> will be merged with the
corresponding models.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-at" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-at">at</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line595" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Get a model from a collection, specified by index. Useful if your collection
is sorted, and if your collection isn't sorted, <code>at</code> will still retrieve
models in insertion order.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-attach" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-attach">attach</a></span><span class="parenthesis">(</span><span class="item-name">ids</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<<a href="api.html#Collection">Collection</a>></span>
          <a href="lib_relation.js.html#line661" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">ids</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
><code class="type-or">|</code><code class="param-type"
  >mixed[]</code
>
</span></code>
      

      <div class="description">
        <p>One or more ID values or models to be attached to the relation.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>A hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">transacting</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<<a href="api.html#Collection">Collection</a>></code
>




<span class="param-desc">
  <p>A promise resolving to the updated Collection where this method was called.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Attaches one or more <code>ids</code> or models from a foreign table to the current
table, on a many-to-many relation. Creates and saves a new
model and attaches the model with the related model.</p>
<pre><code>var admin1 = new Admin({username: 'user1', password: 'test'});
var admin2 = new Admin({username: 'user2', password: 'test'});

Promise.all([admin1.save(), admin2.save()])
  .then(function() {
    return Promise.all([
    new Site({id: 1}).admins().attach([admin1, admin2]),
    new Site({id: 2}).admins().attach(admin2)
  ]);
})
</code></pre>
<p>This method (along with <a href="api.html#Collection-instance-detach"><code>Collection#detach</code></a> and <a href="api.html#Collection-instance-updatePivot"><code>Collection#updatePivot</code></a>) are mixed in to a <a href="api.html#Collection"><code>Collection</code></a> when
returned by a <a href="api.html#Model-instance-belongsToMany"><code>belongsToMany</code></a> relation.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-clone" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-clone">clone</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line650" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    
    <dt class="tag-overrides">Overrides</dt>
    <dd class="tag-overrides"><ul class="dummy"><li>
        <a href="api.html#CollectionBase-instance-clone">CollectionBase#clone</a>
    </li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Create a new collection with an identical list of models as this one.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-detach" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-detach">detach</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">ids</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<undefined></span>
          <a href="lib_relation.js.html#line698" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">ids</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
><code class="type-or">|</code><code class="param-type"
  >mixed[]</code
>
</span></code>
      

      <div class="description">
        <p>One or more ID values or models to be detached from the relation.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>A hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">transacting</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<undefined></code
>




<span class="param-desc">
  <p>A promise resolving to the updated Collection where this method was called.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Detach one or more related objects from their pivot tables. If a model or
id is passed, it attempts to remove from the pivot table based on that
foreign key. If no parameters are specified, we assume we will detach all
related associations.</p>
<p>This method (along with <a href="api.html#Collection-instance-attach"><code>Collection#attach</code></a> and <a href="api.html#Collection-instance-updatePivot"><code>Collection#updatePivot</code></a>) are mixed in to a <a href="api.html#Collection"><code>Collection</code></a> when returned
by a <a href="api.html#Model-instance-belongsToMany"><code>belongsToMany</code></a> relation.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-first" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-first">first</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a>|undefined</span>
          <a href="lib_base_collection.js.html#line139" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >undefined</code
>




<span class="param-desc">
  <p>The first model or <code>undefined</code>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns the first model in the collection or <code>undefined</code> if the collection is empty.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-get" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-get">get</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a></span>
          <a href="lib_base_collection.js.html#line583" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const book = library.get(110);</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
>




<span class="param-desc">
  <p>The model, or <code>undefined</code> if it is not in the collection.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Get a model from a collection, specified by an <a href="api.html#Model-instance-id"><code>id</code></a>, a <code>cid</code>, or by passing in a <a href="api.html#Model"><code>model</code></a>.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-invokeThen" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-invokeThen">invokeThen</a></span><span class="parenthesis">(</span><span class="item-name">method</span><span class="comma">, </span><span class="variable-ellipsis">&hellip;</span><span class="item-name">arguments</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<mixed[]></span>
          <a href="lib_base_collection.js.html#line381" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">method</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The <a href="api.html#Model"><code>model</code></a> method to invoke.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="variable-ellipsis">&hellip;</span><span class="item-name">arguments</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>Arguments to <code>method</code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<mixed[]></code
>




<span class="param-desc">
  <p>Promise resolving to array of results from invocation.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Shortcut for calling <code>Promise.all</code> around a <code>Collection#invoke</code>, this
will delegate to the collection's <code>invoke</code> method, resolving the promise with
an array of responses all async (and sync) behavior has settled. Useful for
bulk saving or deleting models:</p>
<pre><code>collection.invokeThen('save', null, options).then(function() {
  // ... all models in the collection have been saved
});

collection.invokeThen('destroy', options).then(function() {
  // ... all models in the collection have been destroyed
});</code></pre>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-last" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-last">last</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a>|undefined</span>
          <a href="lib_base_collection.js.html#line148" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  >undefined</code
>




<span class="param-desc">
  <p>The last model or <code>undefined</code>.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Returns the last model in the collection or <code>undefined</code> if the collection is empty.</p>
    </div>
  
</div>

          
              
<div class="method no-description">
    

        <h4 id="Collection-instance-off" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-off">off</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line68" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>ships.off('fetched') // Remove the 'fetched' event listener</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Events-instance-off">Events#off</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-on" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-on">on</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line56" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const ships = new bookshelf.Collection
ships.on('fetched', function(collection) {
  // Do something after the data has been fetched from the database
})</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Events-instance-on">Events#on</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Registers an event listener.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-once" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-once">once</a></span><span class="parenthesis">(</span><span class="item-name">nameOrNames</span><span class="comma">, </span><span class="item-name">callback</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_events.js.html#line104" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">nameOrNames</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the event or space separated list of events to register a
callback for.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">callback</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>That callback to invoke only once when the event is fired.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Just like <a href="api.html#Events-instance-on"><code>Events#on</code></a>, but causes the bound callback to fire only
once before being removed. Handy for saying &quot;the next time that X happens,
do this&quot;. When multiple events are passed in using the space separated
syntax, the event will fire once for every event you passed in, not once
for a combination of all events.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-orderBy" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-orderBy">orderBy</a></span><span class="parenthesis">(</span><span class="item-name">column</span><span class="comma">, </span><span class="item-name">order</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line475" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>Cars.forge().orderBy('color', 'ASC').fetch()
   .then(function (rows) { // ...</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">column</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column to sort on.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">order</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Ascending (<code>'ASC'</code>) or descending (<code>'DESC'</code>) order.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    
    <dt class="tag-since">Since</dt>
    <dd class="tag-since"><ul class="dummy"><li>0.9.3</li></ul></dd>
    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Specifies the column to sort on and sort order.</p>
<p>The order parameter is optional, and defaults to 'ASC'. You may
also specify 'DESC' order by prepending a hyphen to the sort column
name. <code>orderBy(&quot;date&quot;, 'DESC')</code> is the same as <code>orderBy(&quot;-date&quot;)</code>.</p>
<p>Unless specified using dot notation (i.e., &quot;table.column&quot;), the default
table will be the table name of the model <code>orderBy</code> was called on.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-parse" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-parse">parse</a></span><span class="parenthesis">(</span><span class="item-name">resp</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line641" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">resp</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object[]</code
>
</span></code>
      

      <div class="description">
        <p>Raw database response array.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>The <code>parse</code> method is called whenever a collection's data is returned in a
<a href="api.html#Collection-instance-fetch"><code>fetch</code></a> call. The function is passed the raw
database <code>response</code> array, and should return an array to be set on the
collection. The default implementation is a no-op, simply passing through
the JSON response.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-pluck" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-pluck">pluck</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  mixed[]</span>
          <a href="lib_base_collection.js.html#line626" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >mixed[]</code
>




<span class="param-desc">
  <p>An array of attribute values.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Pluck an attribute from each model in the collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-pop" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-pop">pop</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line535" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Remove a model from the end of the collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-push" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-push">push</a></span><span class="parenthesis">(</span><span class="item-name">model</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_base_collection.js.html#line526" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object[]</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>One or more models or raw
attribute objects.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Add a model to the end of the collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-query" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-query">query</a></span><span class="parenthesis">(</span><span class="item-name">arguments</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a>|QueryBuilder</span>
          <a href="lib_collection.js.html#line411" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>let qb = collection.query();
    qb.where({id: 1}).select().then(function(resp) {
      // ...
    });

collection.query(function(qb) {
  qb.where('id', '>', 5).andWhere('first_name', '=', 'Test');
}).fetch()
  .then(function(collection) {
    // ...
  });

collection
  .query('where', 'other_id', '=', '5')
  .fetch()
  .then(function(collection) {
    // ...
  });</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">arguments</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The query method.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="http://knexjs.org/#Builder">Knex `QueryBuilder`</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
><code class="type-or">|</code><code class="param-type"
  >QueryBuilder</code
>




<span class="param-desc">
  <p>This collection or, if called with no arguments, the underlying query builder.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This method is used to tap into the underlying Knex query builder instance for the current
collection.</p>
<p>If called with no arguments, it will return the query builder directly, otherwise it will
call the specified <code>method</code> on the query builder, applying any additional arguments from the
<code>collection.query</code> call.</p>
<p>If the <code>method</code> argument is a function, it will be called with the Knex query builder as the
context and the first argument.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-reduceThen" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-reduceThen">reduceThen</a></span><span class="parenthesis">(</span><span class="item-name">iterator</span><span class="comma">, </span><span class="item-name">initialValue</span><span class="comma">, </span><span class="item-name">context</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<mixed></span>
          <a href="lib_base_collection.js.html#line408" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">iterator</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Collection~reduceThenIterator">Collection~reduceThenIterator</a></code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">initialValue</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">context</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Bound to <code>this</code> in the <code>iterator</code> callback.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="http://bluebirdjs.com/docs/api/promise.reduce.html">Bluebird `Promise.reduce` reference</a>.</li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<mixed></code
>




<span class="param-desc">
  <p>Promise resolving to the single result from the reduction.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Iterate over all the models in the collection and reduce this array to a single value using the
given iterator function.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-remove" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-remove">remove</a></span><span class="parenthesis">(</span><span class="item-name">models</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a>|<a href="api.html#Model">Model</a>[]</span>
          <a href="lib_base_collection.js.html#line474" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">models</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
>
</span></code>
      

      <div class="description">
        <p>The model, or models, to be removed.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Set of options for the operation.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">silent</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>If set to <code>true</code> will not trigger a <code>remove</code> event on the removed model.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a></code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
>




<span class="param-desc">
  <p>The same value passed in the <code>models</code> argument.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Remove a <a href="api.html#Model"><code>model</code></a>, or an array of models, from the collection. Note that this does not remove the affected
models from the database. For that purpose you have to use the model's <a href="api.html#Model-instance-destroy"><code>destroy</code></a> method.</p>
<p>If you wish to actually remove all the models in a collection from the database you can use this method:</p>
<pre><code>myCollection.invokeThen('destroy').then(() =&gt; {
  // models have been destroyed
})</code></pre>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-reset" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-reset">reset</a></span><span class="parenthesis">(</span><span class="item-name">models</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Model">Model</a>[]</span>
          <a href="lib_base_collection.js.html#line509" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">models</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object[]</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>One or more models or raw
attribute objects.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>See <a href="api.html#Collection-instance-add"><code>add</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
>




<span class="param-desc">
  <p>Array of models.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Adding and removing models one at a time is all well and good, but sometimes
you have so many models to change that you'd rather just update the
collection in bulk. Use <code>reset</code> to replace a collection with a new list of
models (or attribute hashes). Calling <code>collection.reset()</code> without passing
any models as arguments will empty the entire collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-serialize" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-serialize">serialize</a></span><span class="parenthesis">(</span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Object</span>
          <a href="lib_base_collection.js.html#line198" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">shallow</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Exclude relations.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">omitPivot</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Exclude pivot values.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">omitNew</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Exclude models that return true for isNew.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Object</code
>




<span class="param-desc">
  <p>Serialized model as a plain object.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Return a raw array of the collection's <code>attributes</code> for JSON stringification. If the <a href="api.html#Model"><code>models</code></a> have any
relations defined, this will also call <a href="api.html#Model-instance-toJSON"><code>toJSON</code></a> on
each of the related objects, and include them on the object unless
<code>{shallow: true}</code> is passed as an option.</p>
<p><code>serialize</code> is called internally by <a href="api.html#Collection-instance-toJSON"><code>toJSON</code></a>.
Override this function if you want to customize its output.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-set" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-set">set</a></span><span class="parenthesis">(</span><span class="item-name">models</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_base_collection.js.html#line257" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>var vanHalen = new bookshelf.Collection([eddie, alex, stone, roth]);
vanHalen.set([eddie, alex, stone, hagar]);</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">models</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object[]</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a>[]</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>One or more models or raw
attribute objects.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options for controlling how models are added or removed.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">add</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>If set to <code>true</code> it will add any new models to the collection, otherwise
any new models will be ignored.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">merge</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>If set to <code>true</code> it will merge the attributes of duplicate models with the
attributes of existing models in the collection, otherwise duplicate
models in the list will be ignored.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">remove</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">true</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>If set to <code>true</code> any models in the collection that are not in the list
will be removed from the collection, otherwise they will be kept.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The set method performs a smart update of the collection with the passed
model or list of models by following the following rules:</p>
<ul>
<li>If a model in the list isn't yet in the collection it will be added</li>
<li>if the model is already in the collection its attributes will be merged</li>
<li>if the collection contains any models that aren't present in the list,
they'll be removed.</li>
</ul>
<p>If you'd like to customize the behavior, you can do so with the <code>add</code>,
<code>merge</code> and <code>remove</code> options.</p>
<p>Since version 0.14.0 if both <code>remove</code> and <code>merge</code> options are set to
<code>false</code>, then any duplicate models present will be added to the collection,
otherwise they will either be removed or merged, according to the chosen
option.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-shift" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-shift">shift</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line555" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Remove a model from the beginning of the collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-slice" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-slice">slice</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line566" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Slice out a sub-array of models from the collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-through" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-through">through</a></span><span class="parenthesis">(</span><span class="item-name">Interim</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">throughForeignKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">otherKey</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">throughForeignKeyTarget</span><span class="optional-bracket">]</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">otherKeyTarget</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_collection.js.html#line114" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>const Chapter = bookshelf.model('Chapter', {
  tableName: 'chapters',
  paragraphs() {
    return this.hasMany(Paragraph)
  }
})

const Paragraph = bookshelf.model('Paragraph', {
  tableName: 'paragraphs',
  chapter() {
    return this.belongsTo(Chapter)
  }
})

const Book = bookshelf.model('Book', {
  tableName: 'books',
  // Find all paragraphs associated with this book, by
  // passing through the "Chapter" model.
  paragraphs() {
    return this.hasMany(Paragraph).through(Chapter)
  }
})</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Interim</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>Pivot model.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">throughForeignKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in this collection's model. This is the model that the <code>hasMany</code> or
<code>belongsToMany</code> relations return. By default, the <code>foreignKey</code> is assumed to be the
singular form of the <code>Target</code> model's tableName, followed by <code>_id</code> /
<code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">otherKey</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Foreign key in the <code>Interim</code> model. By default, the <code>otherKey</code> is assumed to be the
singular form of this model's tableName, followed by <code>_id</code> /
<code>_{{<a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a>}}</code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">throughForeignKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in this collection's model which <code>throughForeignKey</code> references, if other than the
default of the model's <code>id</code> / <code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">otherKeyTarget</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Column in the <code>Interim</code> model which <code>otherKey</code> references, if other than <code>id</code> /
<code><a href="api.html#Model-instance-idAttribute"><code>idAttribute</code></a></code>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>The related but empty collection.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Used to define relationships where a <a href="api.html#Model-instance-hasMany"><code>hasMany</code></a> or
<a href="api.html#Model-instance-belongsToMany"><code>belongsToMany</code></a> relation passes &quot;through&quot; an <code>Interim</code> model. This
is exactly like the equivalent <a href="api.html#Model-instance-through"><code>model method</code></a> except that it applies to
the collections that the above mentioned relation methods return instead of individual
models.</p>
<p>A good example of where this would be useful is if a book <a href="api.html#Model-instance-hasMany"><code>hasMany</code></a>
paragraphs <em>through</em> chapters. See the example above for how this can be used.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-toJSON" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-toJSON">toJSON</a></span><span class="parenthesis">(</span><span class="item-name">Options</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line213" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">Options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >options</code
>
</span></code>
      

      <div class="description">
        <p>passed to <a href="api.html#Collection-instance-serialize"><code>Collection#serialize</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Called automatically by <a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior"><code>JSON.stringify</code></a>. To customize serialization, override <a href="api.html#Collection-instance-serialize"><code>serialize</code></a>.</p>
    </div>
  
</div>

          
              
<div class="method no-description">
    

        <h4 id="Collection-instance-trigger" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-trigger">trigger</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line77" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>ships.trigger('fetched')</code></pre>

      </div>
    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Events-instance-trigger">Events#trigger</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
  </div>

  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-triggerThen" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-triggerThen">triggerThen</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise</span>
          <a href="lib_base_events.js.html#line80" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The event name or a whitespace-separated list of event names to be triggered.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>Arguments to be passed to any registered event handlers.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>A promise resolving to the return values of any triggered handlers.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>A promise version of <a href="api.html#Events-instance-trigger"><code>Events#trigger</code></a>, returning a promise which
resolves with all return values from triggered event handlers. If any of the
event handlers throw an <code>Error</code> or return a rejected promise, the promise
will be rejected. Used internally on the <a href="api.html#Model-event-creating"><code>"creating"</code></a>,
<a href="api.html#Model-event-updating"><code>"updating"</code></a>, <a href="api.html#Model-event-saving"><code>"saving"</code></a>, and
<code>"destroying"</code> events, and can be helpful when needing
async event handlers (e.g. for validations).</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-unshift" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-unshift">unshift</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line546" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Add a model to the beginning of the collection.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-updatePivot" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-updatePivot">updatePivot</a></span><span class="parenthesis">(</span><span class="item-name">attributes</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise<Number></span>
          <a href="lib_relation.js.html#line725" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">attributes</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Values to be set in the <code>update</code> query.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">options</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>A hash of options.</p>
        
          

<ul class="params">
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">query</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
><code class="type-or">|</code><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Constrain the update query. Similar to the <code>method</code> argument to <a href="api.html#Model-instance-query"><code>Model#query</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">require</span><span class="default-value"><span class="default-equals">=</span><span class="default-value">false</span></span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Boolean</code
>
</span></code>
      

      <div class="description">
        <p>Causes promise to be rejected with an Error if no rows were updated.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="item-name">transacting</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Transaction</code
>
</span></code>
      

      <div class="description">
        <p>Optionally run the query in a transaction.</p>
        
      </div>

    </li>
  
</ul>

        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise<Number></code
>




<span class="param-desc">
  <p>A promise resolving to number of rows updated.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The <code>updatePivot</code> method is used exclusively on <a href="api.html#Model-instance-belongsToMany"><code>belongsToMany</code></a> relations, and allows for updating pivot rows on the joining
table.</p>
<p>This method (along with <a href="api.html#Collection-instance-attach"><code>Collection#attach</code></a> and <a href="api.html#Collection-instance-detach"><code>Collection#detach</code></a>) are mixed in to a <a href="api.html#Collection"><code>Collection</code></a> when returned
by a <a href="api.html#Model-instance-belongsToMany"><code>belongsToMany</code></a> relation.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-where" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-where">where</a></span><span class="parenthesis">(</span><span class="item-name">conditions</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_collection.js.html#line453" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    
      <div class="example">
        <h5>Example</h5>
        
    <pre class="prettyprint"><code>collection
  .where('favorite_color', '&lt;>', 'green')
  .fetch()
  .then(results => {
    // ...
  })

// or

collection
  .where('favorite_color', 'red')
  .fetch()
  .then(results => {
    // ...
  })

collection
  .where({favorite_color: 'red', shoe_size: 12})
  .fetch()
  .then(results => {
    // ...
  })</code></pre>

      </div>
    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">conditions</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
><code class="type-or">|</code><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>Either <code>key, [operator], value</code> syntax, or a hash of attributes to match. Note that these
must be formatted as they are in the database, not how they are stored after
<a href="api.html#Model-instance-parse"><code>Model#parse</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-see">See</dt>
    <dd class="tag-see">
        <ul>
            <li><a href="api.html#Collection-instance-query">Collection#query</a></li>
        </ul>
    </dd>
    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>This is used as convenience for the most common <a href="api.html#Collection-instance-query"><code>query</code></a> method:
adding a <code>WHERE</code> clause to the builder. Any additional knex methods may be accessed using
<a href="api.html#Collection-instance-query"><code>query</code></a>.</p>
<p>Accepts either <code>key, value</code> syntax, or a hash of attributes to constrain the results.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Collection-instance-withPivot" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-instance-withPivot">withPivot</a></span><span class="parenthesis">(</span><span class="item-name">columns</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  <a href="api.html#Collection">Collection</a></span>
          <a href="lib_relation.js.html#line753" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">columns</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string[]</code
>
</span></code>
      

      <div class="description">
        <p>Names of columns to be included when retrieving pivot table rows.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>




<span class="param-desc">
  <p>Self, this method is chainable.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>The <code>withPivot</code> method is used exclusively on <a href="api.html#Model-instance-belongsToMany"><code>belongsToMany</code></a> relations, and allows for additional fields to be pulled
from the joining table.</p>
<pre><code>var Tag = bookshelf.model('Tag', {
  comments: function() {
    return this.belongsToMany(Comment).withPivot(['created_at', 'order']);
  }
});</code></pre>
    </div>
  
</div>

          
        </div>
    

    
        <h3
          id="Collection-subsection-lodash-methods"
          class="subsection-title"
        >Lodash Methods</h3>
        <ul class="lodash-methods">
          
              <li id="Collection-instance-countBy" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#countBy">countBy</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-every" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#every">every</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-filter" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#filter">filter</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-find" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#find">find</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-forEach" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#forEach">forEach</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-groupBy" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#groupBy">groupBy</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-includes" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#includes">includes</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-invokeMap" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#invokeMap">invokeMap</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-isEmpty" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#isEmpty">isEmpty</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-map" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#map">map</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-reduce" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#reduce">reduce</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-reduceRight" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#reduceRight">reduceRight</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-reject" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#reject">reject</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-some" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#some">some</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-sortBy" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#sortBy">sortBy</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
              <li id="Collection-instance-toArray" class="lodash-method">
  <span class="parameters"><span class="name"><a href="http://lodash.com/docs/#toArray">toArray</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
</li>

          
        </ul>
    

    
        <h3 class="subsection-title">Type Definitions</h3>

        
                
<div class="method has-description">
    

        <h4 id="Collection~reduceThenIterator" class="item-header">
          <span class="type-signature"></span>
          
          <span class="parameters"><span class="name"><a href="api.html#Collection~reduceThenIterator">reduceThenIterator</a></span><span class="parenthesis">(</span><span class="item-name">acumulator</span><span class="comma">, </span><span class="item-name">model</span><span class="comma">, </span><span class="item-name">index</span><span class="comma">, </span><span class="item-name">length</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_collection.js.html#line385" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">acumulator</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">model</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Model">Model</a></code
>
</span></code>
      

      <div class="description">
        <p>The current model being iterated over.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">index</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Number</code
>
</span></code>
      

      <div class="description">
        
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">length</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Number</code
>
</span></code>
      

      <div class="description">
        <p>Total number of models being iterated over.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>This iterator is used by the reduceThen method to ietrate over all models in the collection.</p>
    </div>
  
</div>

            
    

    
        <h3
          id="Collection-subsection-events"
          class="subsection-title"
        >Events</h3>

        
            
<div class="method has-description">
    

        <h4 id="Collection-event-fetched" class="item-header">
          
          
          <span class="member-of"
                ><span class="class-name"
                  >collection</span
                >.</span><span class="event-on">on</span><span class="parenthesis">(</span><a href="api.html#Collection-event-fetched">"fetched"</a><span class="comma">, </span> <span class="parenthesis">(</span><span class="item-name">collection</span><span class="comma">, </span><span class="item-name">response</span><span class="comma">, </span><span class="item-name">options</span><span class="parenthesis">)</span> <span class="fat-arrow">=&gt;</span>
          <a href="lib_collection.js.html#line183" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">collection</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  ><a href="api.html#Collection">Collection</a></code
>
</span></code>
      

      <div class="description">
        <p>The collection performing the <a href="api.html#Collection-instance-fetch"><code>Collection#fetch</code></a>.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">response</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Knex query response.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">options</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >Object</code
>
</span></code>
      

      <div class="description">
        <p>Options object passed to <a href="api.html#Collection-instance-fetch"><code>fetch</code></a>.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    
    <dt class="tag-tutorial">Tutorials</dt>
    <dd class="tag-tutorial">
        <ul>
            <li><a href="tutorial-events.html">Events</a></li>
        </ul>
    </dd>
    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>





        
  </div>

  
    <div class="item-description">
        <p>Fired after a <code>fetch</code> operation. A promise may be returned from the
event handler for async behaviour.</p>
    </div>
  
</div>

        
    
</article>


    





<article>
    
        <h2 id="section-Collection-static-EmptyError">
            <span class="ancestors"><a href="api.html#Collection">Collection</a>.</span
        >EmptyError</h2>
        
    

    <div class="container-overview">
    
        <h3
          id="Collection-static-EmptyError-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Collection-static-EmptyError" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="member-of"
                ><span class="class-name"
                  >Collection</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Collection-static-EmptyError">EmptyError</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_collection.js.html#line533" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Thrown by default when no records are found by <a href="api.html#Collection-instance-fetch"><code>fetch</code></a> or
<a href="api.html#Collection-instance-fetchOne"><code>Collection#fetchOne</code></a>. This behavior can be overrided with the
<a href="api.html#Model-instance-requireFetch"><code>Model#requireFetch</code></a> option.</p>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    

    

    

    

    

    
</article>

















<article>
    
        <h2 id="section-Events">Events</h2>
        
    

    <div class="container-overview">
    
        <h3
          id="Events-subsection-construction"
          class="subsection-title"
        >Construction</h3>
        
<div class="method has-description">
    

        <h4 id="Events" class="item-header">
          <span class="type-signature"></span>
          
            <span class="new">new</span>
          
          <span class="parameters"><span class="name"><a href="api.html#Events">Events</a></span><span class="parenthesis">(</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_events.js.html#line12" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Base Event class inherited by <a href="api.html#Model"><code>Model</code></a> and <a href="api.html#Collection"><code>Collection</code></a>. It's not
meant to be used directly, and is only displayed here for completeness.</p>
    </div>
  
</div>

        

    
    </div>

    

    

     

    

    

    

    
        <h3
          id="Events-subsection-methods"
          class="subsection-title"
        >Methods</h3>
        <div class="methods">
          
              
<div class="method has-description">
    

        <h4 id="Events-instance-off" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >events</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Events-instance-off">off</a></span><span class="parenthesis">(</span><span class="item-name">nameOrNames</span><span class="comma">, </span><span class="item-name">callback</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_events.js.html#line35" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">nameOrNames</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the event or space separated list of events to stop listening
to.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">callback</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>That callback to remove.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Remove a previously-bound callback event listener from an object. If no
event name is specified, callbacks for all events will be removed.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Events-instance-on" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >events</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Events-instance-on">on</a></span><span class="parenthesis">(</span><span class="item-name">nameOrNames</span><span class="comma">, </span><span class="item-name">callback</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  mixed</span>
          <a href="lib_base_events.js.html#line19" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">nameOrNames</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name or space separated names of events to register a callback for.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">callback</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>That callback to invoke whenever the event is fired.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >mixed</code
>




<span class="param-desc">
  <p>The object where this is called on is returned to allow chaining this method call.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>Registers an event listener. The callback will be invoked whenever the event is fired. The event string may also be
a space-delimited list of several event names.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Events-instance-once" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >events</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Events-instance-once">once</a></span><span class="parenthesis">(</span><span class="item-name">nameOrNames</span><span class="comma">, </span><span class="item-name">callback</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_events.js.html#line104" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">nameOrNames</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the event or space separated list of events to register a
callback for.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="item-name">callback</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >function</code
>
</span></code>
      

      <div class="description">
        <p>That callback to invoke only once when the event is fired.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Just like <a href="api.html#Events-instance-on"><code>Events#on</code></a>, but causes the bound callback to fire only
once before being removed. Handy for saying &quot;the next time that X happens,
do this&quot;. When multiple events are passed in using the space separated
syntax, the event will fire once for every event you passed in, not once
for a combination of all events.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Events-instance-trigger" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >events</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Events-instance-trigger">trigger</a></span><span class="parenthesis">(</span><span class="item-name">nameOrNames</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"></span>
          <a href="lib_base_events.js.html#line60" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">nameOrNames</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The name of the event to trigger. Also accepts a space separated list of
event names.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>Extra arguments to pass to the event listener callback function.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
  </div>

  
    <div class="item-description">
        <p>Trigger callbacks for the given event, or space-delimited list of events.
Subsequent arguments to <code>trigger</code> will be passed along to the event
callback.</p>
    </div>
  
</div>

          
              
<div class="method has-description">
    

        <h4 id="Events-instance-triggerThen" class="item-header">
          <span class="type-signature"></span>
          
          <span class="member-of"
                ><span class="class-name"
                  >events</span
                >.</span><span class="parameters"><span class="name"><a href="api.html#Events-instance-triggerThen">triggerThen</a></span><span class="parenthesis">(</span><span class="item-name">name</span><span class="comma">, </span><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span><span class="parenthesis">)</span></span><span class="type-signature"> &rarr;  Promise</span>
          <a href="lib_base_events.js.html#line80" class="source-link">source</a>
        </h4>

        
    

  <div class="attributes">

    

    

    

    

    
        <h5>Parameters</h5>
        

<ul class="params">
  
    <li>
      <code class="param"><span class="item-name">name</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >string</code
>
</span></code>
      

      <div class="description">
        <p>The event name or a whitespace-separated list of event names to be triggered.</p>
        
      </div>

    </li>
  
    <li>
      <code class="param"><span class="optional-bracket">[</span><span class="variable-ellipsis">&hellip;</span><span class="item-name">args</span><span class="optional-bracket">]</span></code>

      
          <code class="param-type"><span class="param-type"
            ><code class="param-type"
  >mixed</code
>
</span></code>
      

      <div class="description">
        <p>Arguments to be passed to any registered event handlers.</p>
        
      </div>

    </li>
  
</ul>

    

    


<dl class="details">

    

    

    

    

    

    

    

    

    

    

    

    

    

    
</dl>


    

    

    

    

    

    
    <h5>Returns</h5>
    
            


<code class="param-type"
  >Promise</code
>




<span class="param-desc">
  <p>A promise resolving to the return values of any triggered handlers.</p>
</span>


        
  </div>

  
    <div class="item-description">
        <p>A promise version of <a href="api.html#Events-instance-trigger"><code>Events#trigger</code></a>, returning a promise which
resolves with all return values from triggered event handlers. If any of the
event handlers throw an <code>Error</code> or return a rejected promise, the promise
will be rejected. Used internally on the <a href="api.html#Model-event-creating"><code>"creating"</code></a>,
<a href="api.html#Model-event-updating"><code>"updating"</code></a>, <a href="api.html#Model-event-saving"><code>"saving"</code></a>, and
<code>"destroying"</code> events, and can be helpful when needing
async event handlers (e.g. for validations).</p>
    </div>
  
</div>

          
        </div>
    

    

    

    
</article>







        </div>
      </div>
    </div>

    <footer>
      <div>
        Documentation generated by
        <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a>
        
          on
          June 7, 2020
        
      </div>
    </footer>

    <script>prettyPrint();</script>
    <script src="scripts/linenumber.js"></script>
    <script src="scripts/main.js"></script>
  </body>
</html>